@rehearsal-db/core 1.1.0 → 1.2.0

package/docs/commands.md

@@ -10,6 +10,138 @@ versioned migration history with required predecessor links, statuses, warnings,
 the exact complete candidate digest. Filters never change the required ordered suffix;
 Rehearsal does not infer SQL safety from filenames.
 
+### Static Migration Insights
+
+In a core build advertising `rehearsalContracts.migrationInsights: 1`, run
+`npx --no-install rehearsal inspect insights --json` to inspect pending SQL without
+starting an engine, connecting to a database, running application commands or changing
+files. This additive contract does not change `inspect plan` version 1. It is new
+development work, not a capability of the original tested core 1.1.0 candidate.
+
+The normal version-1 command envelope contains `data.schemaVersion: 1`, the exact
+complete `candidateSha256`, candidate count, aggregate verdict and per-target entries.
+Each entry binds its version, filename, SHA-256 and nullable safe workspace-relative
+path to fixed findings. Findings expose only a rule, severity, one-based line and
+UTF-16 column, fixed summary and suggestion—never SQL snippets, object names or row
+values. Locations identify the static construct, not the origin of a later provider
+error. Refresh after editing; editor navigation must recheck the source hash.
+
+Rules flag table/column removal, truncation, UPDATE/DELETE without an outer WHERE,
+NOT NULL requirements, new constraints and recognized CASCADE clauses. Comments,
+strings, quoted identifiers and routine bodies are not reinterpreted as executable
+statements. CTE mutations are considered separately from the outer statement.
+
+Verdicts are `static_warnings`, `no_detected_warning`, and `unknown`.
+**No detected warning does not mean safe, syntactically valid or database-verified.**
+Coverage describes recognized lexical rules only. Unsupported statements, malformed
+lexical input, runtime-dependent plain-string escaping and bounded/truncated analysis
+remain unknown. A file can retain a warning while its overall coverage is unknown.
+This is not a full PostgreSQL parser or a predictor of row loss, constraint compliance,
+locks, rollback, permissions, production performance or external effects. Use the
+ordinary reviewed rehearsal and application proof for actual behavior.
+
+Input is limited to 10,000 SQL files across targets, 10,000 directory entries per
+migration directory (including non-SQL entries), 1,000 pending candidates, 2 MiB per
+file and 16 MiB total. Lexical analysis is bounded to 20,000 tokens and depth
+128 per file; findings are bounded to 1,000 per file and 5,000 total. Symlinks, escaping
+paths, unsafe filenames, invalid UTF-8 and changed input refuse inspection. Exceeded
+lexical/finding bounds produce incomplete coverage rather than a safety verdict.
+The CLI and these essential safety warnings remain free.
+
+### Current-sandbox data impact
+
+A source build advertising `rehearsalContracts.migrationImpact: 1` adds two free,
+optional commands. This is unpublished development work, not a capability of an
+already-installed release. It does not change migration-plan v1, static Insights,
+failure diagnosis, or the gates for `run` and `migrate`.
+
+```bash
+npx --no-install rehearsal inspect impact --target=primary --json
+npx --no-install rehearsal measure impact --target=primary \
+  --confirm-candidates=<whole-plan-sha256-from-the-preview> --json
+```
+
+Both commands require an explicit configured target name, even for `primary`.
+`inspect impact` reads the reviewed project inputs only: it does not contact a
+database, start an engine, run SQL, apply migrations, or change files. Its preview
+binds planned aggregate kinds to the exact whole-project candidate digest, selected
+target, baseline generation, and each candidate filename and hash. In a multi-target
+project, confirmation still uses the **whole-plan** digest, not the selected target's
+digest. Editing any target's pending migrations requires a fresh preview.
+
+`measure impact` requires that exact confirmation and an already-running, verified,
+ownership-proven disposable local sandbox. It refuses an unavailable, stale or
+unmanaged runtime rather than starting, repairing or resetting it. The existing
+project-operation lock prevents a concurrent Rehearsal mutation; operation lock files
+and bounded local activity history may be written. A bounded read-only catalog
+preflight retains eligible relation identities. The counts then use one
+`REPEATABLE READ READ ONLY` transaction, which is rolled back after the counts.
+Neither command executes pending migrations or application commands.
+Measurements use the selected local sandbox's administrative connection, not the
+application's role. They inspect stored data, not application permissions; RLS-enabled
+or otherwise unsupported objects remain unknown. No application grants are changed.
+
+Before the count snapshot, Rehearsal locks eligible measured relations in a fixed
+order with `SHARE ROW EXCLUSIVE`. These locks temporarily block writers and
+index/statistics/schema changes on that disposable sandbox; ordinary readers can
+continue. They use the same 1-second lock wait and remaining total budget. Name
+lookup also holds a bounded `SHARE` lock on the selected database's namespace
+catalog to prevent concurrent schema renames; this temporarily blocks schema
+catalog changes across that database and requires sufficient local privileges.
+A relation name swapped to a view between preflight and locking may transiently lock that view's
+dependencies inside the selected sandbox, but the retained-identity/type check
+refuses its counts without executing the view query. This is not atomic name
+resolution or protection against a compromised PostgreSQL server/catalog.
+See PostgreSQL's [locking behavior](https://www.postgresql.org/docs/17/sql-lock.html).
+
+The narrow recognizer supports simple, schema-qualified, unquoted SQL forms for:
+
+| Recognized change                                               | Aggregate on the current sandbox                        |
+| --------------------------------------------------------------- | ------------------------------------------------------- |
+| Drop a table, truncate one table, or delete without a predicate | Row count                                               |
+| Drop one column                                                 | Rows whose current column is not NULL                   |
+| Set one column NOT NULL                                         | Rows whose current column is NULL                       |
+| Add a simple UNIQUE constraint                                  | Rows in non-NULL duplicate groups, not only excess rows |
+| Add a simple FOREIGN KEY with MATCH SIMPLE semantics            | Non-NULL referencing rows with no match                 |
+
+Measurements require PostgreSQL 17 or newer with server-side transaction deadlines,
+ordinary non-inherited, non-partitioned heap tables without RLS, and supported built-in
+column/operator semantics. Older or unsupported server semantics remain unknown;
+Rehearsal never upgrades a database to obtain counts. Quoted identifiers, CHECK constraints,
+UPDATE, predicates, CASCADE, expressions, routines, custom types/operators and other
+unsupported forms remain unknown. The recognizer is not a PostgreSQL parser. A table
+created or a column changed by an earlier pending migration is **not** simulated: all
+counts describe the same current snapshot before any pending migration. Row counts
+do not measure cascade, trigger or external effects, prove constraint validity, or
+predict production locking, performance, data loss or safety.
+
+The version-1 result includes the exact candidate/target bindings, `mode`
+(`preview` or `measurement`), `measurementStatus`, nullable snapshot time and runtime
+identity hash, per-file coverage/unknown reasons, and fixed operation/metric kinds
+with lexical locations. Public counts are decimal **strings**, including `"0"`;
+`null` means unavailable, never zero. No SQL, database object names or row contents
+are returned. `planned` preview status may contain unsupported input and is not
+measurement evidence. Measurement status is `measured`, `partial`, `unknown`, or
+`not_required`. Partial or unknown measurement returns envelope `status: "not_ready"`
+and exit `1`, retaining only the available evidence; neither a successful envelope
+nor zero counts is a safety verdict.
+
+The same bounded migration-input rules as static Insights apply. A review plans at
+most 100 aggregates. Measurement uses a 1-second lock timeout, 5-second statement
+timeout, 30-second total budget, 128 KiB output limit and 256 KiB generated-script
+limit. The server transaction budget is reduced after runtime identity checks and
+catalog preflight; it is never increased to compensate for a slow check.
+Lock/statement/budget failures remain unknown instead of returning guessed counts.
+Client cancellation is not by itself proof of immediate server-backend termination;
+server-side deadlines additionally bound owned query/transaction lifetime.
+Package-owned cancellation supports the ordinary cancellation signals,
+releases the project lock and returns exit `130`; it does not reset or discard data.
+Older editor versions may refuse the new `measure impact` operation kind in current
+activity or retained history. This source command does not itself update the editor;
+use the CLI until a compatible editor consumer is released.
+Continue to use the normal reviewed rehearsal and application proof for actual
+migration behavior.
+
 `npx rehearsal configuration --json` identifies the exact active config, its source
 fingerprint, validated field metadata, and saved named profiles. To validate an edit
 without writing it, use `npx rehearsal configuration review --proposal=review.json --json`.
@@ -132,20 +264,22 @@ obsolete placeholder key.
 
 ## Check and inspect
 
-| Command                            | What it does                                                            |
-| ---------------------------------- | ----------------------------------------------------------------------- |
-| `npx rehearsal doctor`             | Check dependencies, inputs, and safety rules.                           |
-| `npx rehearsal discover`           | Explain detected facts, suggestions, and decisions.                     |
-| `npx rehearsal support`            | Print a privacy-safe report for a support request.                      |
-| `npx rehearsal activity`           | Report whether another Rehearsal operation is active.                   |
-| `npx rehearsal environments`       | Show owned runtimes, live resource use, and Docker capacity.            |
-| `npx rehearsal resources`          | Browse images, volumes, container references, and cleanup explanations. |
-| `npx rehearsal explain`            | Show the exact plan without changing anything.                          |
-| `npx rehearsal run --dry-run`      | Show the same non-mutating plan.                                        |
-| `npx rehearsal candidates`         | List pending migrations and their approval digest.                      |
-| `npx rehearsal inspect baseline`   | Show active and retained baseline metadata without row values.          |
-| `npx rehearsal inspect migrations` | Classify every historical and candidate migration.                      |
-| `npx rehearsal status`             | Report baseline, candidates, and local runtime state.                   |
+| Command                                                                      | What it does                                                            |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `npx rehearsal doctor`                                                       | Check dependencies, inputs, and safety rules.                           |
+| `npx rehearsal discover`                                                     | Explain detected facts, suggestions, and decisions.                     |
+| `npx rehearsal support`                                                      | Print a privacy-safe report for a support request.                      |
+| `npx rehearsal activity`                                                     | Report whether another Rehearsal operation is active.                   |
+| `npx rehearsal environments`                                                 | Show owned runtimes, live resource use, and Docker capacity.            |
+| `npx rehearsal resources`                                                    | Browse images, volumes, container references, and cleanup explanations. |
+| `npx rehearsal explain`                                                      | Show the exact plan without changing anything.                          |
+| `npx rehearsal run --dry-run`                                                | Show the same non-mutating plan.                                        |
+| `npx rehearsal candidates`                                                   | List pending migrations and their approval digest.                      |
+| `npx rehearsal inspect baseline`                                             | Show active and retained baseline metadata without row values.          |
+| `npx rehearsal inspect migrations`                                           | Classify every historical and candidate migration.                      |
+| `npx rehearsal inspect impact --target=<name>`                               | Preview exact aggregate kinds without contacting a database.            |
+| `npx rehearsal measure impact --target=<name> --confirm-candidates=<sha256>` | Read bounded aggregates from that current verified sandbox.             |
+| `npx rehearsal status`                                                       | Report baseline, candidates, and local runtime state.                   |
 
 State-reporting commands accept `--json` for scripts. Scripts should use the JSON fields
 and process exit code, not parse human-facing text.
@@ -359,7 +493,7 @@ Clients should disable conflicting actions unless the state is `idle`.
 
 ### Cancelling a mutation
 
-`run`, `reset`, `migrate`, confirmed `refresh`, and direct or guided `open` preparation support
+`run`, `reset`, `migrate`, `measure impact`, confirmed `refresh`, and direct or guided `open` preparation support
 package-owned cancellation.
 Send `SIGINT`, `SIGTERM`, `SIGHUP`, or `SIGTSTP` to the Rehearsal CLI process. Rehearsal
 handles repeated delivery as one request, forwards it only to the detached process group
@@ -472,25 +606,26 @@ belonging to other projects are never included. This follows
 
 ## Common options
 
-| Option                                 | Meaning                                                          |
-| -------------------------------------- | ---------------------------------------------------------------- |
-| `--help`, `-h`                         | Show the installed command reference.                            |
-| `--version`, `-V`                      | Print the installed package version and exit.                    |
-| `--json`                               | Return the versioned machine-readable result.                    |
-| `--verbose`                            | Show more safe detail.                                           |
-| `--debug`                              | Show the most diagnostic detail; still review it before sharing. |
-| `--plain`                              | Disable decorative interactive prompts.                          |
-| `--config=<path>`                      | Use only this config for planning and every runtime action.      |
-| `--target=supabase\|postgresql`        | Choose the setup target.                                         |
-| `--include-runtime`                    | Include this project's runtime in a cleanup preview.             |
-| `--include-images`                     | Include older unused Supabase images in a cleanup preview.       |
-| `--confirm-cleanup=<digest>`           | Confirm the exact cleanup set printed by the preview.            |
-| `--confirm-source-access=<digest>`     | Confirm one exact temporary source-access plan.                  |
-| `--confirm-source-retirement=<digest>` | Confirm exact source-access retirement.                          |
-| `--confirm-refresh=<digest>`           | Confirm an exact refresh, runtime reset, and old-copy removal.   |
-| `--identity=<name>`                    | Choose one declared local identity association.                  |
-| `--confirm-identity=<digest>`          | Confirm that exact local identity plan.                          |
-| `--write`                              | Apply a setup, policy, or cleanup preview.                       |
+| Option                                 | Meaning                                                                                         |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `--help`, `-h`                         | Show the installed command reference.                                                           |
+| `--version`, `-V`                      | Print the installed package version and exit.                                                   |
+| `--json`                               | Return the versioned machine-readable result.                                                   |
+| `--verbose`                            | Show more safe detail.                                                                          |
+| `--debug`                              | Show the most diagnostic detail; still review it before sharing.                                |
+| `--plain`                              | Disable decorative interactive prompts.                                                         |
+| `--config=<path>`                      | Use only this config for planning and every runtime action.                                     |
+| `--target=<name>`                      | Choose a setup provider or configured runtime target; impact commands require an explicit name. |
+| `--confirm-candidates=<digest>`        | Confirm the exact whole-plan candidates for run, migrate or impact measurement.                 |
+| `--include-runtime`                    | Include this project's runtime in a cleanup preview.                                            |
+| `--include-images`                     | Include older unused Supabase images in a cleanup preview.                                      |
+| `--confirm-cleanup=<digest>`           | Confirm the exact cleanup set printed by the preview.                                           |
+| `--confirm-source-access=<digest>`     | Confirm one exact temporary source-access plan.                                                 |
+| `--confirm-source-retirement=<digest>` | Confirm exact source-access retirement.                                                         |
+| `--confirm-refresh=<digest>`           | Confirm an exact refresh, runtime reset, and old-copy removal.                                  |
+| `--identity=<name>`                    | Choose one declared local identity association.                                                 |
+| `--confirm-identity=<digest>`          | Confirm that exact local identity plan.                                                         |
+| `--write`                              | Apply a setup, policy, or cleanup preview.                                                      |
 
 Run `npx rehearsal --help` to print the command list available in your installed version.
 Run `npx rehearsal --version` to print only its version number. Add `--json` when a

package/docs/configuration.md

@@ -289,11 +289,29 @@ Colima. It warns at `diskWarningPercent` and refuses to start below
 generated PostgreSQL configs reserve 2 GiB. Engines that do not expose a portable disk
 measurement continue normally and report capacity as unavailable in `environments`.
 
-`supabase.serviceProfile` is `application` by default. It retains the database, Auth,
-Storage, PostgREST, gateway, and local mail service while omitting Studio, Realtime, Edge
-Functions, analytics, Vector, and image transforms. Choose `full` only when the project
-proof actually exercises one of those services. PostgreSQL remains the lighter choice
-when the proof needs only SQL, migrations, triggers, or sanitized relational data.
+Choose the smallest reviewed environment that supplies the proof's dependencies:
+
+| Proof needs                                                      | Select                                                                                   | Retained dependencies and boundary                                                                                                         |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| SQL migrations, schema, triggers, or sanitized relational data   | `runtime.target: "postgresql"`                                                           | One PostgreSQL container; no native Supabase Auth, Storage, or Data API.                                                                   |
+| Supabase Auth, Storage, or Data API behavior                     | `runtime.target: "supabase"` with `supabase.serviceProfile: "application"` (the default) | Keep database, Auth, Storage, PostgREST, gateway, and local mail together. Direct SQL alone does not prove these application-facing paths. |
+| Studio, Realtime, Edge Functions, analytics, or image transforms | Supabase with `serviceProfile: "full"`                                                   | Remove Rehearsal's exclusions, retain the application dependencies, and explicitly enable the needed services in the reviewed TOML.        |
+
+The application profile omits Studio, Realtime, Edge Functions, analytics, Vector, and
+image transforms. These are reviewed bundles, not permission to trim individual services
+with ad hoc CLI flags. Declare what the proof uses through
+[`application.requiredServices`](#required-application-services); a conflicting profile
+or disabled required service refuses before startup. Profile selection does not change
+data retention, shared-engine ownership, or supported-platform boundaries.
+
+Compare resource measurements only for the same exact package, fixture, engine, and
+hardware. Test Lab's fresh-container startup measurement includes provisioning, health
+checks, and baseline restoration on an already-running engine; record whether images
+were cached. It does not measure VM boot or uncached-image downloads. Owned-container CPU/memory
+samples are not host/VM memory reservations or an application-load soak test. Keep these
+limits with the results rather than comparing mixed-version samples as an optimization.
+Do not prune shared images or restart another project's engine to obtain a benchmark.
+See [resource inspection](runtime-lifecycle.md#diagnosing-unexpected-activity).
 
 After each Supabase start, Rehearsal changes only the exact target's containers to
 Docker's `no` restart policy. Its database and Storage volumes remain intact,

package/docs/index.md

@@ -33,6 +33,7 @@ you want, then follow the links when a term or safety check is new.
 | Set up my own project                    | [Getting started](getting-started.md)                             |
 | Use the free visual workbench in VS Code | [Install VS Code Starter](vscode.md)                              |
 | Try Rehearsal without touching my app    | [Hands-on tutorial](tutorial.md)                                  |
+| Check changes, compatibility or updates  | [Releases and updates](updating.md)                               |
 | Understand what makes a copy safe        | [Baselines](baselines.md) and [Sanitization](sanitization.md)     |
 | Look up a command or setting             | [CLI commands](commands.md) and [Configuration](configuration.md) |
 | Reduce Docker and Supabase resource use  | [Container runtime lifecycle](runtime-lifecycle.md)               |

package/docs/releasing.md

@@ -1,4 +1,8 @@
-# Release process
+# Maintainers: publishing Rehearsal
+
+**Audience: Rehearsal maintainers publishing a release.** To install or update
+Rehearsal in your own project, use [Releases and updates](updating.md).
+The publisher controls below are not steps that ordinary users need to perform.
 
 This page defines required release controls, not a certification that a publisher is
 currently ready. Verify the live repository, trusted-publisher identity and approval
@@ -15,9 +19,9 @@ back to a token or disable provenance. The release preflight described below enf
 that refusal; an actual held approval and the npm account settings still need direct
 verification. A local working tree is never the release source.
 
-`0.1.0-beta.0` was prepared under the unavailable `@rehearsal` npm scope and was never
-published. `0.1.0-beta.1` supersedes that candidate under `@rehearsal-db/core` without
-rewriting the earlier Git tag or GitHub prerelease.
+This runbook describes the current controls. Historical candidates and release incidents
+belong in [release history](https://github.com/Ddupasquier/rehearsal-db/releases) and
+[issues](https://github.com/Ddupasquier/rehearsal-db/issues), not the installation path.
 
 ## Trusted publication boundary
 
@@ -37,11 +41,9 @@ private therefore cannot preserve this release contract unchanged. Keep the revi
 release source public; never silently remove provenance. See
 [npm's trusted-publisher guidance](https://docs.npmjs.com/trusted-publishers/).
 
-The initial `0.1.0-beta.1` package creation required a one-time bootstrap credential
-because npm cannot configure a trusted publisher before a package exists. That
-credential is not part of the maintained release architecture: it was deleted from the
-GitHub environment after publication, must remain revoked at npm, and cannot be consumed
-by this workflow.
+Bootstrap credentials are not part of the maintained release architecture. Any historical
+bootstrap credential must remain removed from GitHub and revoked at npm; this workflow
+cannot consume it. Do not replace a failing trusted publisher with a stored token.
 
 A failed candidate does not permit moving or deleting its release tag. If its pinned
 workflow needs a source correction, prepare a new version and artifact through the same

package/docs/roadmap.md

@@ -61,6 +61,25 @@ release or consumer upgrade remains unfinished:
 - Remove consumer integration code only after its replacement passes and that deletion
   is separately approved.
 
+## Efficient local execution and optional managed runs
+
+Efficient local profiles, data-preserving lifecycle controls, essential safety and the
+complete CLI stay free. Resource improvements must preserve the services and representative
+data needed to prove the chosen scenario; a database-only pass is not full application
+acceptance. See [choosing a local profile](runtime-lifecycle.md#choosing-postgresql-or-supabase).
+
+Optional managed execution is the paid-service direction: run demanding rehearsals
+without a local database stack. It is not currently available. Its design must establish
+explicit upload consent, isolated execution, credential and retention boundaries,
+verifiable cleanup and bounded costs before a hosted launch. Sanitization does not
+automatically authorize uploading a baseline. Pricing and commercial terms remain separate.
+
+The [resource-efficiency initiative](https://github.com/Ddupasquier/rehearsal-db/issues/208)
+coordinates existing lifecycle work and bounded remote/native feasibility. Experimental
+upstream native runtimes are not a supported Rehearsal replacement merely because they
+can omit Docker. Moving an application's production host does not itself reduce the
+services a local rehearsal needs.
+
 ## Later database targets
 
 Additional database, runtime, identity-provider and migration-tool integrations require

package/docs/runtime-lifecycle.md

@@ -191,6 +191,16 @@ These observations help compare profiles, not promise a machine-wide memory budg
 A cold-image or fresh-VM benchmark needs its own disposable, exclusive test environment.
 Do not prune shared images or restart a shared engine to manufacture a cold measurement.
 
+### Free local efficiency and planned managed execution
+
+Efficient local profiles, the complete CLI and essential lifecycle/data protections stay
+free. Choose the smallest profile that still proves the requested behavior; Rehearsal
+does not silently remove declared Auth, Storage or API dependencies to save memory.
+
+Optional managed execution is planned separately and is not available in this release.
+Choosing a local profile does not upload data or authorize a hosted operation. See the
+[product direction](roadmap.md#efficient-local-execution-and-optional-managed-runs).
+
 ## Scheduled review and stale-stop safety
 
 Resource policies configure advisory retention, measured-volume budgets, and scheduled

package/docs/updating.md

@@ -0,0 +1,73 @@
+# Releases and updates
+
+The CLI and VS Code extension update separately. Their version numbers do not need to
+match. Updating a package does not run migrations or reset your database.
+
+## What changed?
+
+Read the [CLI release notes](https://github.com/Ddupasquier/rehearsal-db/releases) or
+[extension release notes](https://github.com/Ddupasquier/rehearsal-vscode/releases)
+for the version you plan to install. Each component has its own release history.
+
+## Is my environment supported?
+
+Rehearsal supports Node.js 22, 24 and 26 on macOS and Linux. On Windows, run database
+commands in a WSL 2 Linux workspace; native PowerShell and Command Prompt are not
+supported database runtimes. The WSL route remains a preview, not a claim of native
+Windows database support. See [supported environments and limitations](https://github.com/Ddupasquier/rehearsal-db/blob/main/COMPATIBILITY.md)
+and the [Windows setup guide](getting-started.md#windows-use-a-wsl-2-linux-workspace)
+before installing.
+
+## How do I update?
+
+### VS Code extension
+
+Open **Extensions**, find **Rehearsal DB** (`rehearsal-db.rehearsal-db`), and choose
+**Update** when available. Save your work and reload only when you are ready, if VS Code
+asks. For a direct download, follow the [verified VSIX instructions](vscode.md#direct-github-installation).
+
+Prefer automatic updates? Open **Rehearsal: Check for Updates** and save the extension
+and/or CLI options you want. They are independent, initially off, and can be disabled
+later. An unavailable network, busy project or incompatible update may defer installation.
+See [automatic updates](vscode.md#optional-automatic-updates) for consent and privacy details.
+
+Using the legacy preview through 0.1.18? Follow the [one-time identity migration](vscode.md#move-from-a-preview-through-0118)
+instead of installing both extension identities together.
+
+### Project CLI package
+
+Finish active Rehearsal commands first. Read the [release notes](https://github.com/Ddupasquier/rehearsal-db/releases),
+then use your project's existing package manager and dependency location. For an npm
+project that keeps Rehearsal in development dependencies, update to the reviewed 1.2.0
+release only after it appears in the official registry:
+
+```bash
+npm install --save-dev --save-exact @rehearsal-db/core@1.2.0
+npx --no-install rehearsal --version
+```
+
+Review the package and lockfile changes before the next Rehearsal command.
+
+## Breaking changes or known limitations?
+
+Check the target release notes before upgrading. Breaking upgrades, the move from a
+0.x preview to stable core, and local source/tarball installations need deliberate
+review rather than an automatic switch. See the [compatibility promise](stability.md#what-becomes-a-compatibility-promise)
+or [troubleshooting](troubleshooting.md) when an update is refused.
+
+Do not delete keys, baselines or sandbox data to update. Updating does not authorize
+production access or make an unsupported database or platform supported. Keep the
+[data-safety boundaries](security-model.md) and explicit reset/discard warnings in
+force; a successful rehearsal is not a guarantee that deployment is safe.
+
+## Where can I verify the package's origin?
+
+Use the official [npm package](https://www.npmjs.com/package/@rehearsal-db/core),
+[VS Code Marketplace listing](https://marketplace.visualstudio.com/items?itemName=rehearsal-db.rehearsal-db)
+or linked GitHub releases. npm provenance links the CLI package to its public release
+source and build. For a direct VSIX download, follow the [SHA-256 verification steps](vscode.md#direct-github-installation).
+Origin verification does not replace reviewing a release's compatibility or safety limits.
+
+You do not need publisher credentials, GitHub deployment approvals or the maintainer
+release checklist to install or update Rehearsal. Those belong to the
+[maintainer publishing guide](releasing.md).

package/docs/vscode.md

@@ -4,9 +4,9 @@ The Rehearsal extension turns the local CLI into a project-aware database-change
 workbench. It is for developers who want the safety of exact migration plans and disposable
 local runtimes without memorizing every command.
 
-This guide targets **Free Starter 0.1.23**, named **Rehearsal DB** on
+This guide targets **Free Starter 0.1.24**, named **Rehearsal DB** on
 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=rehearsal-db.rehearsal-db),
-with a [reviewed GitHub VSIX](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.23)
+with a [reviewed GitHub VSIX](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.24)
 for direct installation. The canonical extension ID is **`rehearsal-db.rehearsal-db`**,
 published by **`rehearsal-db`**. The workbench and commands retain the **Rehearsal** brand.
 All included features are free indefinitely for personal or commercial development.
@@ -24,6 +24,9 @@ identity. This is not an automatic rename or uninstall.
 
 - See what Rehearsal detected, what it suggests, and what still needs your decision.
 - Review, filter, sort, and check off the exact pending migration set.
+- Read optional static Migration Insights with core 1.2.0 and open unchanged source
+  at a lexical finding. Unsupported analysis stays unknown; no warning is a safety
+  verdict or proof of valid SQL. No database is started or contacted for this analysis.
 - Inspect targets, runtime state, retained baseline generations, local ports, and app URLs.
 - Review safe configuration changes as an exact diff before writing them.
 - Launch the same public CLI operations with their exact command and confirmation intact.
@@ -66,8 +69,9 @@ real WSL core fixtures do not certify a native Remote-WSL editor walkthrough.
 4. Follow **Next best step**. Review the detected project and active configuration;
    setup, source access, migration execution and cleanup keep their own confirmations.
 
-The release pairing described here is core **1.0.2** with Starter **0.1.23**.
-Install it once both versions appear in their official release channels.
+Core and the extension have independent version numbers. This guide targets core
+**1.2.0** and Starter **0.1.24**, only once each is published. See [Updates](updating.md)
+when moving an existing installation forward.
 The extension's minimum core is `0.1.0-rc.4`. A project that is not ready should show
 setup guidance, not require you to build the extension. Opening the dashboard does not
 start a database or run a migration. Use
@@ -92,10 +96,10 @@ distinction between desktop OS, extension host, architecture and actual database
 ### Direct GitHub installation
 
 The verified GitHub VSIX is an alternative to Marketplace. Open the
-[Starter 0.1.23 release](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.23).
-Under **Assets**, download `rehearsal-db-0.1.23.vsix` and `SHA256SUMS`. In a terminal,
-run `shasum -a 256 /path/to/rehearsal-db-0.1.23.vsix` on macOS or
-`sha256sum /path/to/rehearsal-db-0.1.23.vsix` on Linux. Compare the result with that
+[Starter 0.1.24 release](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.24).
+Under **Assets**, download `rehearsal-db-0.1.24.vsix` and `SHA256SUMS`. In a terminal,
+run `shasum -a 256 /path/to/rehearsal-db-0.1.24.vsix` on macOS or
+`sha256sum /path/to/rehearsal-db-0.1.24.vsix` on Linux. Compare the result with that
 release's `SHA256SUMS`; stop if they differ. Do not substitute a local rebuild.
 Then open **Extensions → … → Install from VSIX…** and choose the verified file.
 Save your work and reload only if VS Code asks.
@@ -227,7 +231,7 @@ route; do not delete its coordination lock while a package manager may still be
 
 Manual updating stays available: download and verify the next reviewed VSIX, then repeat
 **Install from VSIX…**. See the release's
-[installation guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.23/README.md#install-and-open-your-project).
+[installation guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.24/README.md#install-and-open-your-project).
 An ordinary core-package update is detected from its manifest, lockfile and installed
 metadata without reloading VS Code. The header shows loaded extension and core versions
 separately; installed → newest appears only after a successful release check. Unknown or
@@ -236,16 +240,18 @@ offline availability is not proof that you are up to date.
 ## Privacy boundary
 
 Passive inspection stays local. The extension includes no telemetry, advertising, hosted
-database access, or account. It does not read environment files, credentials, private rows,
-baseline contents, or project source during passive inspection. An explicit migration
+database access, or account. It does not read environment files, credentials, private rows
+or baseline contents. With the optional Insights capability, core also reads bounded
+project-local migration files and returns fixed findings, not SQL bodies or row values.
+No SQL is executed or uploaded and no database is contacted for static analysis. An explicit migration
 source action reads only the selected local input to check its approved bytes before
 opening it in the editor; it does not upload SQL. User-approved package operations and
 external links may use their own services.
 
 ## License, support and future Pro
 
-Starter 0.1.23 carries the same
-[free Starter license](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.23/LICENSE).
+Starter 0.1.24 carries the same
+[free Starter license](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.24/LICENSE).
 Its current review, configuration, comparison and reporting tools are included; they
 are not a timed evaluation or a paid feature gate. Free use does not mean the extension
 is MIT-licensed: its bundled terms govern copying and redistribution. Core remains MIT.
@@ -254,17 +260,17 @@ Future optional Pro editor workflows must be separately identified. They cannot
 retroactively remove Starter rights already granted for a received version. Pro pricing,
 billing and entitlements are not implemented; no payment is needed to use Starter.
 Database and safety capabilities stay in the free CLI. The
-[edition guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.23/docs/commercial-readiness.md)
+[edition guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.24/docs/commercial-readiness.md)
 owns the detailed boundary.
 
 Preview describes stability, not a trial countdown. Support is best effort, with no
 service-level agreement, database hosting, backups or production support. Before use,
-read the release's [privacy statement](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.23/PRIVACY.md)
-and [support policy](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.23/SUPPORT.md).
+read the release's [privacy statement](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.24/PRIVACY.md)
+and [support policy](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.24/SUPPORT.md).
 Report editor problems in the
 [Rehearsal issue tracker](https://github.com/Ddupasquier/rehearsal-db/issues), as
 described in the support policy.
-Use its [private security process](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.23/SECURITY.md)
+Use its [private security process](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.24/SECURITY.md)
 for vulnerabilities; never post credentials, private rows or baseline files publicly.
 
 Historical VSIX files retain their bundled terms. Choose a reviewed release carrying

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": false,
   "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
   "repository": {
@@ -27,6 +27,8 @@
     "resourceInventory": 1,
     "resourceManager": 1,
     "migrationReview": 1,
+    "migrationInsights": 1,
+    "migrationImpact": 1,
     "configurationReview": 1,
     "baselineShape": 1
   },