@rehearsal-db/core 0.1.0-beta.9 → 0.1.0-rc.2

package/docs/production-source.md

@@ -23,6 +23,15 @@ The privacy key stays ignored under `.rehearsal`. The policy is safe to review i
 control because it contains hashes and environment-variable names, not credentials,
 URLs, or raw owner identifiers.
 
+`credentialFile` must be inside the selected target's
+`baseline.artifactDirectory`, under its `secrets` folder. With the default artifact
+directory, use `.rehearsal/secrets/source-reader.env`. For a target whose artifact
+directory is `targets/primary/.rehearsal`, use
+`targets/primary/.rehearsal/secrets/source-reader.env` and place `privacyKey` there as
+well. Rehearsal stores that target's access receipt beside its baseline at
+`targets/primary/.rehearsal/source-access-receipt.json`; separate targets never share
+the receipt or credential.
+
 ## 2. Declare the source boundary
 
 `source-access-policy.json` uses this shape:
@@ -33,6 +42,7 @@ URLs, or raw owner identifiers.
   "targetFingerprint": "<sha256 of the approved PostgreSQL host, port, and database>",
   "administratorEnvironmentVariable": "REHEARSAL_SOURCE_ADMIN_URL",
   "reader": {
+    "mode": "managed",
     "role": "rehearsal_example_reader",
     "ownerRole": "rehearsal_example_owner",
     "credentialFile": ".rehearsal/secrets/source-reader.env",
@@ -61,7 +71,7 @@ URLs, or raw owner identifiers.
       "view": "approved_owner_profile",
       "targetSchema": "app_api",
       "targetTable": "profiles",
-      "columns": ["id", "email"],
+      "columns": ["id", "email", "avatar_path"],
       "orderBy": ["id"],
       "rowScope": {
         "kind": "approved-owner",
@@ -70,10 +80,28 @@ URLs, or raw owner identifiers.
       }
     }
   ],
-  "assets": []
+  "assetReader": {
+    "endpointFingerprint": "<sha256 of the approved Storage endpoint>",
+    "baseUrlEnvironmentVariable": "REHEARSAL_SOURCE_STORAGE_URL",
+    "tokenEnvironmentVariable": "REHEARSAL_SOURCE_STORAGE_TOKEN",
+    "maximumObjects": 1000,
+    "maximumObjectBytes": 52428800,
+    "maximumTotalBytes": 2147483648
+  },
+  "assets": [
+    {
+      "bucket": "avatars",
+      "prefixEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_ID",
+      "rights": "approved-owner",
+      "pathMapping": "owner-storage"
+    }
+  ]
 }
 ```
 
+`managed` is the default for existing policies, but writing it explicitly makes the
+credential boundary easier to review.
+
 Calculate fingerprints with the exported helpers from `@rehearsal-db/core/source-access`
 or a reviewed local script. A fingerprint binds the destination without recording its
 address. Changing the host, port, or database invalidates the plan.
@@ -82,13 +110,92 @@ address. Changing the host, port, or database invalidates the plan.
 use. `approved-owner` requires one explicit owner value from the named environment
 variable. Rehearsal never chooses an owner by finding an administrator.
 
+### Use a provider-managed reader
+
+If a database owner already supplies the restricted export views and reader, use
+`mode: "external"`. Omit `administratorEnvironmentVariable`; Rehearsal will not request
+an administrator credential or change the source:
+
+```json
+{
+  "reader": {
+    "mode": "external",
+    "role": "provided_rehearsal_reader",
+    "allowedMemberships": ["provided_rehearsal_readers"],
+    "connectionEnvironmentVariable": "REHEARSAL_SOURCE_READER_URL",
+    "credentialFile": ".rehearsal/secrets/source-reader.env",
+    "maximumValidForMinutes": 30
+  },
+  "exportSchema": "provided_rehearsal_export",
+  "relations": [
+    {
+      "source": { "schema": "private", "table": "profiles" },
+      "view": "approved_owner_profile",
+      "targetSchema": "app_api",
+      "targetTable": "profiles",
+      "columns": ["id", "email", "avatar_path"],
+      "orderBy": ["id"],
+      "rowScope": {
+        "kind": "approved-owner",
+        "column": "id",
+        "valueEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_ID"
+      },
+      "viewDefinitionSha256": "<sha256 from externalViewDefinitionFingerprint>"
+    }
+  ]
+}
+```
+
+The database owner must create a `security_barrier` view owned by a role other than the
+reader. Record PostgreSQL's exact canonical definition, not handwritten SQL:
+
+```js
+import { externalViewDefinitionFingerprint } from "@rehearsal-db/core/source-access";
+
+console.log(externalViewDefinitionFingerprint(canonicalViewDefinition));
+```
+
+Obtain `canonicalViewDefinition` with
+`select pg_get_viewdef('provided_rehearsal_export.approved_owner_profile'::regclass, false)`.
+Rehearsal verifies that fingerprint before saving any local access receipt.
+The resulting receipt also binds the normalized source-policy fingerprint. Editing the
+view hash, columns, scopes, or reader declaration requires a new verification.
+
+External mode also requires all non-system readable columns to match only the declared
+views and migration-ledger columns. It refuses database, schema, relation, or column
+writes; privileged role attributes; executable non-system security-definer functions;
+a reader-owned view; or a database-enforced expiration beyond
+`maximumValidForMinutes`.
+
+This audit is intentionally conservative: an object-level table, column, sequence, or
+function grant remains disallowed even when its schema currently lacks `USAGE`. Do not
+use schema visibility to hide stale grants. Revoke the object grant or move the approved
+surface behind the reviewed export views; this also avoids relying on behavior of an
+already-open or prepared database session.
+
+An external login may inherit its narrow permissions from provider-owned group roles.
+List every direct group in `allowedMemberships`; omit the field or use `[]` when the
+login has direct grants only. Rehearsal requires the observed membership set to match
+that list exactly. Every allowed group must be non-login and non-privileged, grant
+inheritance to the login, disable both `SET ROLE` and membership delegation, inherit no
+other role, and own none of the export views. PostgreSQL versions that cannot prove the
+per-membership role-switch setting are refused. Rehearsal still evaluates the login's
+complete effective read, write, sequence, and executable-function surface after those
+checks. Adding, removing, or changing a group changes the reviewed plan digest.
+
 `targetSchema` is optional and defaults to `public`. Set it when the restored relation
 belongs elsewhere, and use the same schema in privacy policy version 2. This is relation
 identity, not a request to search every schema.
 
-For Storage, add an `assetReader` block and approved `assets` entries. The reader URL and
-token come from named environment variables. Objects outside the exact bucket/prefix are
-not listed or downloaded. Size, object-count, path, ETag, and exact-byte checks apply.
+For Storage, the reader URL and token come from named environment variables. A public,
+non-identity prefix may use `prefix`. A private owner prefix uses
+`prefixEnvironmentVariable`, `rights: "approved-owner"`, and a `pathMapping` declared in
+the privacy policy below. Its raw value stays out of tracked files and the review plan
+records only its SHA-256. Objects outside the exact bucket/prefix are not listed or
+downloaded. Size, object-count, path, ETag, and exact-byte checks apply.
+Supabase folder entries are traversed recursively beneath that exact prefix. Folder
+entries count toward `maximumObjects`, so the same reviewed limit bounds both the
+directory walk and transferred files. Empty files remain files and are copied normally.
 
 ## 3. Use executable privacy policy version 2
 
@@ -98,6 +205,21 @@ Every selected column has one action and, where required, a bounded recipe:
 {
   "policyVersion": 2,
   "migrationCutoff": "20260101000000",
+  "bindings": {
+    "approved-owner": {
+      "environmentVariable": "REHEARSAL_APPROVED_OWNER_ID",
+      "approvedValueSha256": "<sha256 of the exact approved owner ID>"
+    }
+  },
+  "pathMappings": {
+    "owner-storage": {
+      "binding": "approved-owner",
+      "format": "uuid",
+      "namespace": "account-id",
+      "maximumBytes": 512,
+      "maximumSegments": 8
+    }
+  },
   "tables": [
     {
       "schema": "app_api",
@@ -119,6 +241,14 @@ Every selected column has one action and, where required, a bounded recipe:
           "generated": "NEVER",
           "identity": "NO",
           "foreignKey": null
+        },
+        {
+          "name": "avatar_path",
+          "action": "DERIVE",
+          "recipe": { "kind": "path-map", "mapping": "owner-storage" },
+          "generated": "NEVER",
+          "identity": "NO",
+          "foreignKey": null
         }
       ]
     }
@@ -126,10 +256,13 @@ Every selected column has one action and, where required, a bounded recipe:
 }
 ```
 
-Supported recipes are intentionally small: keyed UUID/email/text/integer pseudonyms,
-explicit constants, bounded date shifts, and fully classified JSON objects. Unknown
-tables, columns, JSON keys, formats, and recipes stop the refresh. There is no JavaScript
-or SQL escape hatch.
+Supported recipes are intentionally small: keyed UUID/email/text/integer/hex/GTIN/URL
+pseudonyms, hexadecimal digests of explicitly named sanitized columns, explicit
+constants, bounded or grouped date shifts, identity-aware path mappings, bounded
+reviewed-identity substitution inside retained text, and fully classified JSON
+structures. Unknown tables, columns, digest inputs, JSON keys, formats, and recipes stop
+the refresh. There is no JavaScript or SQL escape hatch. See
+[Sanitization policy](sanitization.md) for complete path and date examples.
 
 ## 4. Preview, apply, refresh, and retire
 
@@ -146,10 +279,12 @@ npx rehearsal source retire
 npx rehearsal source retire --confirm-source-retirement=<full-sha256>
 ```
 
-`source apply` creates new time-limited roles and export views only when every exact name
-is unused. It verifies the reader cannot read raw tables, write, escalate roles, or call
-an exposed security-definer network function. Externally provisioned readers are not yet
-supported; use the managed reader so Rehearsal can prove its scope and retirement.
+In managed mode, `source apply` creates new time-limited roles and export views only when
+every exact name is unused. It verifies the reader cannot read raw tables, write,
+escalate roles, or call an exposed security-definer network function. In external mode,
+the same command performs only the read-only checks above and stores the already supplied
+credential in the ignored owner-only local file. It never creates, grants, alters, or
+drops a source object.
 
 `refresh` previews the complete replacement first. After exact confirmation, its baseline
 step uses one read-only repeatable-read transaction for the schema shape,
@@ -160,13 +295,36 @@ runtime is rolled back to the previous baseline and runtime. The lower-level `ba
 refresh` command remains available when automation should activate a baseline without
 resetting the runtime or pruning old generations.
 
+Rows committed after the repeatable-read transaction begins belong to the next refresh;
+they cannot leak into the current snapshot midway through streaming. A schema or ledger
+change during preparation stops activation. Malformed batches, network loss, interruption,
+limit overruns, and low disk also leave the previous baseline active. Because `baseline
+refresh` never resets the runtime, local runtime edits remain in place whether that
+baseline-only preparation succeeds or fails.
+
+Privacy `identity` metadata describes PostgreSQL `GENERATED ... AS IDENTITY`, not a
+person or account identifier. UUID account keys normally use `identity: "NO"` while
+remaining explicitly pseudonymized. During restore, Rehearsal consults the actual local
+table for a backing sequence before resetting it; UUID columns never receive numeric
+`max` or `setval` operations.
+
 Storage cannot share PostgreSQL's transaction snapshot. Rehearsal instead verifies each
 object's inventory version and byte count during transfer, then records its SHA-256 in
-the immutable baseline.
+the immutable baseline. For an identity-aware path, the database reference and physical
+destination use the same package-owned pseudonym; the source suffix is preserved.
+
+In managed mode, `source retire` inventories the exact recorded views before removal,
+then removes only those views, the two recorded roles, and local credential/receipt
+files. In external mode, it removes only Rehearsal's local credential and receipt; the
+provider-owned role and views remain untouched. The database-enforced expiration still
+limits access, and the provider may revoke it sooner. Rehearsal does not claim that local
+cleanup revoked a provider-owned credential. Unrelated roles, grants, objects, baselines,
+runtimes, and Docker resources are preserved.
 
-`source retire` inventories the exact recorded views before removal, then removes only
-those views, the two recorded roles, and local credential/receipt files. Unrelated roles,
-grants, objects, baselines, runtimes, and Docker resources are preserved.
+Apply, refresh, and retire always resolve those local files from the active config's
+`baseline.artifactDirectory`. If you switch configs or target roots, Rehearsal refuses
+to retire a receipt from the other target. It also refuses an existing receipt or
+credential rather than overwriting or adopting it.
 
 ## Limits
 

package/docs/releasing.md

@@ -31,10 +31,13 @@ publication must change and prove the workflow before narrowing that permission.
 
 1. Start from protected `main` on a dedicated ticketed release branch.
 2. Verify the exact version, changelog, compatibility notes, and packed file list.
-3. Run unit and contract tests, formatting, package-content and secret audits,
-   dependency audit, clean tarball installation, and the installed Docker fixture.
-4. Have a developer unfamiliar with the implementing project follow the clean-project
-   onboarding. Correct and retest the first confusing, missing, or wrong instruction.
+3. Run `npm run release:verify`. It performs the package checks and every
+   installed-consumer scenario against one tarball, then records the exact package
+   version, SHA-256, environment, commands, timings, and results in
+   `test-results/release-gate/`. Run the dependency audit separately.
+4. When an unfamiliar developer is available, have them follow clean-project onboarding.
+   Correct and retest the first confusing, missing, or wrong instruction. Record when
+   this human observation was unavailable; automated checks must not impersonate it.
 5. Change `private` to `false` only in the reviewed release change.
 6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
    executable, declared runtime dependency inventory, and dependency audit result.
@@ -51,16 +54,25 @@ publication must change and prove the workflow before narrowing that permission.
 11. Replace consuming projects' temporary Git/archive references only on their own
     protected integration branches and rerun their complete verification.
 
-The workflow publishes prereleases under the `beta` dist-tag and refuses a stable
-version. While Rehearsal has no stable release, the workflow also moves `latest` to the
-same reviewed beta. This keeps the npm package page and the ordinary
-`npm install @rehearsal-db/core` command current. When Rehearsal gains a stable release,
-`latest` must switch to the stable line while `beta` continues to identify prereleases.
+The independent Rehearsal Test Lab is the primary pre-release consumer environment.
+Real product integrations provide additional compatibility evidence; they do not
+replace the package-owned release gate or Test Lab.
+
+The workflow publishes beta and release-candidate versions under the `beta` dist-tag.
+While Rehearsal has no stable release, it also moves `latest` to the same reviewed
+prerelease. This keeps the npm package page and the ordinary
+`npm install @rehearsal-db/core` command current. A stable version publishes under
+`latest` without changing `beta`; after that point, later prereleases update only `beta`
+and cannot replace the stable `latest` line. The GitHub prerelease setting must agree
+with the package version or preparation fails.
+
+The objective promotion checklist and compatibility boundary live in
+[Stability and the first stable release](stability.md).
 
 The trusted publisher allows `npm dist-tag` only so this workflow can maintain those two
-tags without a stored npm token. A manual workflow run from `main` can repair the tags
-for the exact prerelease version currently recorded in `package.json`; it cannot publish
-a package or select a different version. The protected `npm` environment still supplies
+tags without a stored npm token. A manual workflow run from `main` can repair the correct
+channel for the exact version currently recorded in `package.json`; it cannot publish a
+package or select a different version. The protected `npm` environment still supplies
 the human approval gate.
 
 Creating the repository, passing CI, extracting the engine, merging a release branch,

package/docs/roadmap.md

@@ -29,8 +29,9 @@ Track the full breakdown in
   invalid migrations, identities, images, persistence, reset, and cleanup.
 - Run the released package in the real reporting consumer and record positives and
   negatives.
-- Directly observe any claimed Google account-picker/callback and unfamiliar-developer
-  onboarding behavior; automation cannot invent that evidence.
+- Directly observe any claimed Google account-picker/callback. Record
+  unfamiliar-developer onboarding behavior when a tester is available; automation cannot
+  invent either kind of human evidence.
 - Remove consumer integration code only after its replacement passes and that deletion
   is separately approved.
 

package/docs/runtime-lifecycle.md

@@ -0,0 +1,99 @@
+# Container runtime lifecycle
+
+Rehearsal uses a local Docker-compatible engine for disposable PostgreSQL and Supabase
+targets. It owns the targets it creates; it does not own the shared engine or another
+project's containers.
+
+## What starts Docker?
+
+Read-only commands such as `doctor`, `status`, `candidates`, `explain`, and `inspect` do
+not start Docker. Commands that create or resume a database—such as `start`, `reset`,
+`run`, and `open`—need an already-running engine.
+
+Generated configurations keep startup explicit:
+
+```js
+containerRuntime: {
+  autoStartColima: false,
+},
+```
+
+With the default, a stopped engine produces an actionable error. Start Docker Desktop,
+Colima, Rancher Desktop, Podman with Docker compatibility, or another supported engine,
+then repeat the command.
+
+Setting `autoStartColima: true` is an explicit convenience opt-in. If Docker is
+unavailable and the `colima` command exists, Rehearsal runs plain `colima start` and
+reports it. Rehearsal does not resize Colima and does not stop the shared engine
+automatically. Starting Docker can also wake unrelated containers that use Docker's
+`always` or `unless-stopped` restart policy.
+
+## What remains after a command?
+
+- `run` stops the application proof process but keeps the database target available for
+  hands-on testing.
+- `open` keeps the application and databases available until the application session is
+  interrupted. The database target remains available afterward.
+- `stop` stops every configured Rehearsal target in reverse dependency order and retains
+  its local data.
+- `start` resumes a stopped target, reusing compatible state.
+- `reset` recreates the target from the active immutable baseline.
+- `discard` removes the selected disposable target. It is the data-destructive runtime
+  operation and retains the immutable baseline.
+
+After Supabase starts, Rehearsal changes only containers with the exact configured
+Supabase project label to Docker's `no` restart policy. This does not remove containers
+or volumes. It prevents a later Docker restart from silently waking stopped Rehearsal
+stacks; `rehearsal start` still resumes them normally.
+
+## A low-memory daily workflow
+
+1. Start your Docker-compatible engine.
+2. Run `rehearsal run` or `rehearsal open`.
+3. When finished, run `rehearsal stop` from the project root.
+4. Check other projects before stopping the shared engine:
+
+   ```bash
+   docker ps
+   ```
+
+5. If nothing else needs Docker, stop the engine using its own command, such as
+   `colima stop`.
+
+Rehearsal intentionally does not infer that every running container belongs to it. It
+also never runs a global Docker prune. Database and Storage volumes are not deleted by
+`stop`.
+
+## Choosing PostgreSQL or Supabase
+
+Use the PostgreSQL target for migration, schema, trigger, privacy, and ordinary relational
+data checks that do not require Supabase services. It uses one database container.
+
+Use the Supabase target when the proof needs Auth, Storage, PostgREST, or the local API
+gateway. Rehearsal already excludes Realtime, Edge Runtime, Analytics/Logflare, and Vector
+from its Supabase stack. A future service-profile feature will make additional optional
+services explicit; until then, do not trade away application fidelity merely to reduce a
+container count.
+
+## Diagnosing unexpected activity
+
+Start with read-only checks:
+
+```bash
+docker context show
+docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Label "com.supabase.cli.project"}}'
+docker stats --no-stream
+colima status
+```
+
+For each container, inspect its project ownership and restart policy before taking any
+action:
+
+```bash
+docker inspect --format '{{json .Config.Labels}} {{.HostConfig.RestartPolicy.Name}}' CONTAINER
+```
+
+Do not remove anonymous volumes or old images based on names alone. Use `rehearsal
+cleanup` for package-owned baseline retention and its reviewed, opt-in image cleanup.
+Shared resource inventory and stale-environment cleanup are tracked separately; until
+that lands, stopping a configured target from its own project is the safe path.

package/docs/runtime-policies.md

@@ -77,9 +77,12 @@ graph without an application callback patch:
   "identities": [
     {
       "name": "approved-owner",
-      "provider": "google",
-      "emailEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_EMAIL",
-      "approvedEmailSha256": "<sha256 of the lowercase approved email>",
+      "matcher": {
+        "type": "verified-email",
+        "providers": ["google"],
+        "emailEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_EMAIL",
+        "approvedEmailSha256": "<sha256 of the lowercase approved email>"
+      },
       "placeholderUserId": "11111111-1111-4111-8111-111111111111",
       "references": [
         {
@@ -152,8 +155,29 @@ graph without an application callback patch:
 }
 ```
 
-The email stays in an environment variable; only its reviewed hash is committed. After
-ordinary local sign-in creates the account, preview and confirm the association:
+Authentication has three separate parts:
+
+1. `config.supabase.authentication` can enable a Google or GitHub connection in local
+   Supabase and reads its credentials from the ignored owner-only environment file.
+   Existing projects may still own that local provider TOML manually. Email sign-in does
+   not use an OAuth credential declaration.
+2. The application completes the ordinary sign-in and receives a normal Supabase
+   session. Rehearsal does not intercept the callback.
+3. The identity policy matches that verified local identity and transfers only the
+   reviewed copied-account graph.
+
+The email stays in an environment variable; only its reviewed hash is committed. The
+guided command keeps the app available for ordinary sign-in, detects the reviewed local
+Auth match, presents a redacted preview, and supplies the exact plan fingerprint
+internally after one confirmation:
+
+```bash
+npx rehearsal identity connect
+```
+
+It never intercepts provider credentials or reads browser state. After connection it
+reopens the app; sign out and sign in once to receive fresh claims. Scripts may retain
+the explicit plan and claim sequence:
 
 ```bash
 npx rehearsal identity plan --identity=approved-owner
@@ -165,6 +189,50 @@ Rehearsal requires exactly one verified matching local provider identity. Every
 `required` reference must exist after transfer. Declare application role tables as
 references; `claims` alone is not a replacement for a database-backed token hook.
 
+### Supported identity matchers
+
+Rehearsal currently supports the Supabase provider values `email`, `google`, and
+`github`. Other provider names fail closed until their Auth representation has package
+coverage. Two matcher types are supported:
+
+- `verified-email` accepts one or more supported providers. It lowercases the email from
+  the named environment variable and compares its SHA-256 receipt before querying Auth.
+- `provider-subject` accepts one OAuth provider (`google` or `github`). It compares the
+  reviewed SHA-256 to Supabase's stable provider ID/subject without placing the raw
+  subject in the policy, baseline, command output, SQL parameters, or receipt.
+
+Google by verified email:
+
+```json
+"matcher": {
+  "type": "verified-email",
+  "providers": ["google"],
+  "emailEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_EMAIL",
+  "approvedEmailSha256": "<sha256 of the lowercase email>"
+}
+```
+
+Supabase email/password or magic-link sign-in uses the same matcher with
+`"providers": ["email"]`. An account intentionally allowed to use either ordinary
+email or Google can declare `"providers": ["email", "google"]`; the claim still refuses
+zero or multiple matching identities.
+
+GitHub by stable provider subject:
+
+```json
+"matcher": {
+  "type": "provider-subject",
+  "provider": "github",
+  "subjectEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_SUBJECT",
+  "approvedSubjectSha256": "<sha256 of the exact GitHub subject>"
+}
+```
+
+Set the raw value only in the local shell or an ignored environment file. Existing
+policies using the older top-level `provider`, `emailEnvironmentVariable`, and
+`approvedEmailSha256` fields remain accepted as a single-provider verified-email
+matcher. New policies should use the explicit `matcher` object.
+
 References use `"strategy": "transfer"` by default. Use `"preserve-audit"` only for
 immutable historical authorship, such as a completed review. Rehearsal leaves that row
 and its synthetic Auth actor unchanged, but still transfers the active profile, roles,
@@ -179,9 +247,14 @@ or unrelated local application data rolls back the entire claim.
 verifies the destination bytes, updates the declared database paths, and then removes
 the old objects. A database failure removes the new copies and leaves the originals
 usable. Restored objects may begin with either the placeholder owner or no owner;
-another owner is refused. `pathReferences` updates matching text or JSONB pointers. A configured
-`tokenHook` must return the declared claim subset before commit. The browser must then
+another owner is refused. `pathReferences` updates matching text or JSONB pointers. A
+configured `tokenHook` must return the declared claim subset before commit. The browser must then
 refresh its session or sign in again because Rehearsal cannot rewrite an issued JWT.
+Run `rehearsal open` again for that fresh-session check; runtime data is preserved.
+
+After a claim, sign out and sign in again (or otherwise force a full token refresh) before
+judging application roles. This preserves normal RLS, account blocks, role checks, and
+MFA; identity association is not an authentication bypass.
 
 The transaction does not import production passwords, sessions, refresh tokens,
 cookies, MFA secrets, or provider credentials. Local MFA and authorization rules remain