@rehearsal-db/core 1.0.1 → 1.0.2

package/dist/src/targets/supabase_start_failure.mjs

@@ -1,4 +1,5 @@
 /** Summarize provider startup evidence without retaining container logs or secrets. */
+import { classifyPortStartupFailure, portStartupGuidance, } from "./port_start_failure.mjs";
 const SERVICE_NAMES = Object.freeze({
     db: "database",
     auth: "auth",
@@ -18,7 +19,6 @@ const SERVICE_NAMES = Object.freeze({
 const REASONS = Object.freeze([
     ["out_of_memory", /out of memory|oom[- ]killed|memory allocation failed/iu],
     ["disk_full", /no space left on device|disk quota exceeded/iu],
-    ["port_in_use", /address already in use|port is already allocated/iu],
     ["image_architecture", /exec format error/iu],
     ["image_pull", /failed to pull|pull access denied|manifest unknown/iu],
     [
@@ -40,6 +40,9 @@ export const summarizeSupabaseStartupFailure = ({ output, status, processErrorCo
         reasons.add("process_timeout");
     if (processErrorCode === "ENOBUFS")
         reasons.add("provider_output_limit");
+    const portFailure = classifyPortStartupFailure(bounded);
+    if (portFailure)
+        reasons.add(portFailure);
     for (const [code, pattern] of REASONS)
         if (pattern.test(bounded))
             reasons.add(code);
@@ -60,6 +63,7 @@ export const summarizeSupabaseStartupFailure = ({ output, status, processErrorCo
         ...(services.size
             ? [`Reported service states: ${[...services].slice(0, 16).join(", ")}.`]
             : []),
+        ...(portFailure ? [portStartupGuidance(portFailure, "supabase")] : []),
         "Provider logs, paths, environment values and connection URLs are omitted. This summary does not establish the underlying cause.",
     ].join("\n");
 };

package/docs/architecture.md

@@ -70,6 +70,24 @@ typed registry and produce the same result contract:
 Command handlers receive an explicit context containing parsed flags, selected config,
 guided state, and session-local caches. They return a rendered, text, or silent result;
 only the shared output boundary creates JSON envelopes or writes final human output.
+`runtime/migration_failure.mts` owns bounded provider-envelope SQLSTATE recognition,
+fixed classification/remediation and closed safe diagnostic validation. Target drivers
+never forward SQL or provider error details. The manager summary reconstructs that
+fixed diagnostic across the child-process boundary; CLI JSON and private operation
+history expose the same projection. Activity adds a separate `recentFailures` list,
+leaving existing strict progress/recent receipt shapes unchanged for old clients.
+The optional `source` projection is owned by `runtime/migration_failure_source.mts`.
+For individually dispatched PostgreSQL files, it identifies the attempted execution
+input by its reviewed filename, exact SHA-256 and baseline/candidate kind. The driver
+hashes the bytes it loads before dispatch; changed reviewed bytes refuse execution.
+Only a safe project-relative candidate path may be included, never an absolute path;
+baseline inputs keep that path null. This is not attribution of the failing SQL's actual
+origin: included scripts, functions and triggers can fail elsewhere. SQL line and column
+remain null. Supabase batch execution currently supplies no file attribution, and
+ambiguous or unavailable evidence is not inferred from candidate count or provider text.
+`cli/failure_output.mts` preserves the outer category and cleanup warning when a
+stack failure wraps the original migration error. It projects only a validated fixed
+diagnosis from at most four original-error wrappers, never cleanup siblings or causes.
 Session caches never appear in the public parsed-flags type.
 Owned child output has a byte boundary. If a process floods it, Rehearsal sends TERM
 and forcibly reaps only that owned process group after one second; a child ignoring
@@ -129,14 +147,18 @@ Each scenario remains independently runnable through its `test:fixture:*` script
 complete release gate runs every catalog entry against the same immutable tarball and
 writes its version, SHA-256, tool environment, commands, timings, and results under
 `test-results/release-gate/`.
+The existing Supabase scenario includes native syntax and populated-row constraint
+failures, fixed public error/history diagnostics, reviewed corrections and independent
+data/Storage preservation checks. It does not infer a rollback from a failed migration.
 
 ## Runtime lifecycle
 
 `runtime/lifecycle_engine.mts` owns the target-neutral lifecycle contract. Both
 PostgreSQL and Supabase use it to dispatch commands, verify active baseline inputs,
 calculate and confirm the exact migration set, write target-bound receipts, validate
-runtime markers, and roll back a failed reset or migration without hiding the original
-failure.
+runtime markers, and attempt owned failure cleanup without hiding the original error.
+That cleanup can remove the disposable runtime; a failure message does not establish a
+SQL transaction rollback, restoration of sandbox edits, or successful resource removal.
 
 The files in `src/targets/` remain drivers. They prove ownership before deleting local
 resources and implement only the behavior that genuinely differs: Docker PostgreSQL
@@ -144,6 +166,14 @@ containers and SQL setup on one side; Supabase CLI, Auth, Storage, and generated
 on the other. An ordinary `stop` never enters rollback or discard, so later `start`
 preserves the sandbox database and Storage contents.
 
+CLI command completion and database lifecycle are separate. A successful `run` can finish
+and release its project lock while the configured keep-until-stop database remains
+running. The project-owned CLI proof has its own primary `application-proof` stage;
+HTTP readiness is optional and is not a prerequisite for a database-only proof. Public
+operation receipts record those past stages, not fresh proof of subsequently changed
+configuration, baseline or migration bytes. Editor presentation consumes that evidence
+without interpreting database liveness as an active command or successful proof.
+
 Repository contracts keep each target driver at 900 lines or fewer and the shared
 lifecycle engine at 300 lines or fewer. A new database target must use this lifecycle
 boundary rather than copying an existing driver's orchestration.

package/docs/commands.md

@@ -238,6 +238,41 @@ provides a stable category, code, safe message, suggestions, diagnostic ID, and
 context under `error`. Callers should use the category and code for decisions and show
 the message and suggestions to people.
 
+Failed migration execution additionally supplies `error.context.migrationFailure`:
+schema version `1`, provider (`postgresql` or `supabase`), classification (`syntax`,
+`schema`, `constraint`, `permission`, `connectivity`, `timeout_or_cancel`, or `unknown`),
+nullable `sqlState`, evidence (`provider_sqlstate`, `unavailable`, or `ambiguous`),
+fixed `summary` and fixed `suggestions`. Classification uses recognized native SQLSTATE
+envelopes, never SQL-text guessing. Unknown evidence does not establish syntax failure.
+Direct manager failures separately name the target in `error.context.target`; raw
+SQL, row values, provider DETAIL, absolute paths and connection strings are not
+included. Optional attempted-input metadata is described below; it does not locate
+the failing SQL statement. Existing exit codes and `MANAGER_RUN_FAILED` / `MANAGER_MIGRATE_FAILED`
+codes are unchanged. If cleanup also fails, the outer failure keeps its existing
+category, exit and cleanup warning while retaining the original fixed migration
+diagnosis. A diagnosis is not borrowed from a cleanup error, and is not evidence that
+cleanup completed.
+
+When PostgreSQL submits one known migration file, the diagnostic may include a closed
+`source` object: schema version `1`, `kind` (`baseline` or `candidate`), `filename`,
+`sha256`, nullable `workspaceRelativePath`, `line: null`, `column: null`, and
+`evidence: "owned_execution_input"`. The loaded bytes must match the reviewed hash.
+This identifies the attempted input, not the exact origin of failing SQL; statements,
+functions and included files can fail elsewhere. No statement counting, provider caret,
+or batch candidate count is converted into a source position. Baseline snapshot paths
+are not exposed; unavailable or ambiguous attribution is omitted, including the
+current Supabase batch path. The editor opens a project-local input only after fresh
+containment, regular-file, identity and exact-byte checks; a changed file needs manual
+review instead of a stale link.
+
+`activity --json` may also provide `data.recentFailures`: up to 20 entries with
+`operationId` and the same `diagnostic`, joined to a failed receipt in `data.recent`.
+Missing means an older producer; `null` means private history is unavailable; `[]`
+means no retained migration diagnosis. These are recent observations, not current
+runtime verification. Existing `recent[]` and progress object fields are unchanged,
+so older clients can ignore the new top-level projection. The local owner-only history
+stores only this fixed safe projection, not arbitrary errors or terminal output.
+
 Invalid positive-integer settings and rejected proposal structure or fields use
 `configuration_invalid` with code `CONFIGURATION_INVALID` (exit `2`), including
 baseline-retention settings and fields that require manual review. They are not

package/docs/getting-started.md

@@ -15,7 +15,7 @@ They are readable helpers, not native executables or bundled Node/Docker install
 Existing Node.js 24 or 26 is required. The default only checks an existing project;
 installation needs an explicit option and does not start a database. Review the
 [shared behavior and release availability](https://github.com/Ddupasquier/rehearsal-db/blob/main/installers/README.md)
-before choosing an install option. An exact core 1.0.1 install requires that version to
+before choosing an install option. An exact core 1.0.2 install requires that version to
 be published; a checked-in helper is not proof of publication.
 
 ### Windows: use a WSL 2 Linux workspace

package/docs/troubleshooting.md

@@ -68,7 +68,9 @@ owner-only startup receipt. This cannot stop a manually started engine.
 When a container stays in `starting` or becomes `unhealthy`, Rehearsal reports a runtime
 dependency failure rather than a migration failure. The safe diagnostic includes Docker
 CPU, memory, and container counts; Colima also includes available VM memory when it can
-be read. Stop unrelated local stacks or increase the engine's resources before retrying.
+be read. These measurements alone do not establish a capacity problem. Review the
+reported startup evidence first; for a proven resource shortage, stop only stacks you
+own or increase the engine's resources before retrying.
 Rehearsal never changes engine settings or bypasses service health checks.
 
 Supabase startup failures retain a bounded summary of recognized provider evidence,
@@ -135,7 +137,7 @@ docker pull postgres:17-alpine
 npx rehearsal doctor
 ```
 
-## A port is already in use
+## A port is already in use or cannot be bound
 
 Rerun `rehearsal setup` to select a different available block. Setup checks both active
 listeners and whether every selected port can be bound, then checks again before writing.
@@ -143,6 +145,56 @@ For an existing configuration, choose unique non-privileged ports and mirror the
 dedicated Supabase config when using Supabase. Do not stop an unrelated database to make
 defaults fit.
 
+`port_in_use` reports an occupied bind; `port_unavailable` reports a denied or
+unavailable bind. Neither proves a memory shortage. On Windows/WSL, an excluded TCP
+range or host access policy can prevent binding even when no listener is visible.
+In **Windows PowerShell**, inspect the host without changing it:
+
+```powershell
+netsh interface ipv4 show excludedportrange protocol=tcp
+```
+
+If the configured port (for example the tutorial's `59422`) is excluded, select a
+different available port outside those ranges. For PostgreSQL, review
+`runtime.databasePort` in `rehearsal.config.mjs`. For Supabase, review the configured
+runtime ports and matching dedicated Supabase configuration together. Keep loopback
+binding. Do not delete reservations, disable host security, prune resources or stop
+someone else's listener to make the default work. Access-denied output is evidence
+of a bind problem, not proof of a particular Windows reservation.
+
+Microsoft documents the [read-only excluded-port command](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/netsh-interface).
+Windows database execution still uses the [WSL 2 compatibility preview](../COMPATIBILITY.md#operating-systems-and-execution-location), not native Windows database support.
+
+## A candidate migration failed, but SQL and provider output are withheld
+
+Rehearsal keeps SQL, row values, constraint names and raw provider output private.
+When the provider supplies a recognized SQLSTATE envelope, it reports that code plus
+a fixed explanation and next step. PostgreSQL codes are
+[provider-defined conditions](https://www.postgresql.org/docs/17/errcodes-appendix.html),
+not guesses from the SQL text:
+
+| Code              | Meaning                | Next step                                                                                 |
+| ----------------- | ---------------------- | ----------------------------------------------------------------------------------------- |
+| `42601`           | SQL syntax error       | Review malformed statements and punctuation.                                              |
+| `23502`           | NOT NULL violation     | Review NULL values and backfill before enforcing the requirement.                         |
+| `23503`           | Foreign-key violation  | Review missing referenced rows and migration ordering.                                    |
+| `23505`           | Uniqueness violation   | Review duplicates before enforcing uniqueness.                                            |
+| `23514`           | CHECK violation        | Existing or newly written rows do not satisfy the constraint; review/backfill them.       |
+| `42P01` / `42703` | Missing table / column | Review schema qualification and migration ordering; this is not a confirmed syntax error. |
+
+Unknown, unsupported, oversized or conflicting evidence remains explicitly unknown;
+it must not be labeled a syntax error from wording alone. JSON failures include the
+versioned `error.context.migrationFailure` projection with provider, classification,
+SQLSTATE, evidence, fixed summary and suggestions. PostgreSQL may identify its exact
+attempted input file, not the actual origin of the failing SQL or a line/column location.
+No automatic rewrite, retry, reset or hosted connection follows a diagnosis.
+
+Inspect `rehearsal status` after failure. Owned runtime cleanup and baseline preservation
+are separate facts; a failed operation does not prove SQL rollback or preservation of
+your disposable sandbox edits. A warning that cleanup could not be confirmed requires
+review before retrying. Follow the [break-and-fix tutorial](tutorial.md#5-break-a-migration-on-existing-data)
+to practice safely on synthetic data.
+
 ## Baseline checksum mismatch
 
 Do not edit the checksum or manifest. The artifact is no longer the reviewed input.

package/docs/tutorial.md

@@ -3,7 +3,7 @@
 This tutorial runs a complete PostgreSQL rehearsal in a temporary fictional project. It
 does not use your application, production data, or a hosted database.
 
-Allow about five minutes after downloading the database image. You need Git, Node.js 22,
+Allow about ten minutes after downloading the database image. You need Git, Node.js 22,
 24, or 26, npm, and a running Docker-compatible engine. Node.js 24 LTS is recommended.
 
 ## 1. Prepare Rehearsal
@@ -36,9 +36,14 @@ rehearsal_repo=$PWD
 tutorial_dir=$(mktemp -d)
 cp -R tests/fixtures/postgresql-project "$tutorial_dir/app"
 cd "$tutorial_dir/app"
-npm install --ignore-scripts --no-save "$rehearsal_repo"
+npm install --ignore-scripts --no-save --install-links "$rehearsal_repo"
 ```
 
+`--install-links` installs a local package copy in this temporary project instead of
+linking to the separate source checkout. Both the CLI and VS Code can use this copy;
+the extension deliberately refuses a package that resolves outside the project or its
+containing Git repository. Installation does not start or change a database.
+
 The temporary project contains:
 
 - one historical migration that creates a `widgets` table;
@@ -51,6 +56,12 @@ The fixture uses runtime ID `rehearsal-postgresql-fixture` and PostgreSQL port `
 Run only one copy at a time, or choose a distinct `runtime.projectId` and free
 `runtime.databasePort` in `rehearsal.config.mjs` before continuing. Rehearsal will not
 replace another listener.
+On Windows, run this tutorial inside WSL 2 on its Linux filesystem, with Linux Node
+and Docker integration enabled. A Windows-excluded port can fail even without a
+listener. If `59422` cannot be bound, inspect the Windows host's excluded TCP ranges
+with `netsh interface ipv4 show excludedportrange protocol=tcp` in PowerShell,
+then choose a different available `runtime.databasePort` before starting. Do not remove
+reservations or stop unrelated services. See [port troubleshooting](troubleshooting.md#a-port-is-already-in-use-or-cannot-be-bound).
 This is a database-only example, not a full application with a browser interface.
 
 ## 3. Create the baseline
@@ -77,10 +88,84 @@ Choose **Run a rehearsal**. The guide should show exactly one candidate:
 Confirm it. Rehearsal creates a loopback-only PostgreSQL container, restores the baseline,
 applies the candidate, and runs the fixture proof.
 
-Success ends with an application-proof message and suggests exercising the local
-application before verification.
+Success ends with the fixture's project-proof message. Here, the configured proof
+checks the migrated database; it does not start a browser application. The rehearsal
+command has finished even though its database can remain running. Continue with the
+deliberate failure below, or use `rehearsal verify` to check the runtime.
+
+## 5. Break a migration on existing data
+
+This is the useful failure: the SQL is valid, but the synthetic row's new `description`
+is NULL. Making that column required would work on an empty table and fail on this row.
+
+Exit the guide. From the temporary app directory, copy the deliberately unsafe example
+into a **new, unapplied** candidate:
+
+```bash
+cp demo/require-description.sql database/migrations/20260101000200_require_widget_description.sql
+npx --no-install rehearsal
+```
+
+Choose **Run a rehearsal** again. Review the two candidates, including the new
+`20260101000200_require_widget_description.sql`, and confirm the exact plan.
+The expected result is a failure, not a successful rehearsal:
+
+```text
+Migration SQLSTATE: 23502.
+Rows do not satisfy a NOT NULL requirement.
+```
+
+The safe explanation recommends reviewing NULL values and backfilling incompatible
+rows. SQL and provider row details remain private. A constraint failure is **not** a
+syntax error: PostgreSQL reported that the data violates the requirement.
+
+Rehearsal must not report the failed runtime as trusted. Its owned failure cleanup may
+remove the disposable runtime; a cleanup warning means resources may remain. The
+immutable baseline remains available. Do not infer a transaction rollback or preserved
+sandbox edits from a failure message alone. No production database is involved.
+
+## 6. Fix it, review again, and pass
+
+Exit the guide. Replace **only this new, never-successfully-applied tutorial candidate**
+with its data-preserving fix:
+
+```bash
+cp demo/backfill-and-require-description.sql database/migrations/20260101000200_require_widget_description.sql
+npx --no-install rehearsal
+```
+
+The fix first fills missing descriptions with a synthetic value, then enforces NOT NULL.
+Choose **Run a rehearsal**, review the changed candidate and its **new digest**, and
+confirm again. Rehearsal restores the same baseline and applies the corrected plan.
+The application proof should now pass. Do not reuse an earlier confirmation or alter a
+historical migration that was already deployed; real deployed history needs a forward
+migration instead.
+
+## 7. Continue in VS Code, or verify from the terminal
+
+To continue in the editor, leave the guide, open this temporary `app` folder in VS Code,
+and install [Rehearsal DB](vscode.md). On Windows, open the folder through **Remote -
+WSL**, not in a native Windows extension host. Trust only this project after reviewing
+its files, then choose **Rehearsal: Open Dashboard**. Refresh if the dashboard was
+already open. Opening or refreshing the dashboard performs read-only inspection; it
+does not rerun the rehearsal or reset its database.
+
+If an earlier tutorial install reports that the package resolves outside its repository,
+run the following from the same temporary `app` directory, using the source checkout
+you built in step 1, then refresh the dashboard:
+
+```bash
+npm install --ignore-scripts --no-save --install-links "$rehearsal_repo"
+```
+
+This replaces the external package link with a project-local copy. Do not edit
+Rehearsal's manifest or CLI paths to bypass the check. The baseline, project
+configuration, privacy key and database do not need to be reset. If the original shell
+was closed, set `rehearsal_repo` to the absolute path of that reviewed source checkout
+first. A copy does not track later source edits; rebuild and explicitly reinstall it
+when testing a changed checkout.
 
-## 5. Try the runtime commands
+## 8. Verify and clean up
 
 Exit the guide, then run:
 
@@ -97,9 +182,9 @@ directory remains on disk and can be deleted when you no longer need it.
 
 ## What you proved
 
-You used the same packaged CLI a normal project installs. Rehearsal verified the baseline,
-approved an exact migration, ran it in a disposable database, tested the result, and
-cleaned up only its own runtime.
+You saw valid SQL fail against existing data, used a safe database explanation to fix
+the unapplied migration, reviewed the changed plan, and proved the correction against
+the same baseline. Rehearsal verified the result and cleaned up only its own runtime.
 
 Next, follow [Getting started](getting-started.md) in your own project. Start with synthetic
 rows until the workflow and application proof are reliable.

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.21**, named **Rehearsal DB** on
+This guide targets **Free Starter 0.1.22**, 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.21)
+with a [reviewed GitHub VSIX](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.22)
 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.
@@ -66,13 +66,21 @@ 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.1** with Starter **0.1.21**.
+The release pairing described here is core **1.0.2** with Starter **0.1.22**.
 Install it once both versions appear in their official release channels.
 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
 [Getting started](getting-started.md) for the CLI and safe baseline inputs.
 
+For the database-only [tutorial](tutorial.md), open that same tutorial folder in VS Code.
+A local npm link outside the project can work in the CLI but fail the editor's package
+containment check. **Project package link needs repair** explains the verified link
+case: install a reviewed published package/tarball, or copy the reviewed local folder
+with `npm install --ignore-scripts --no-save --install-links /path/to/rehearsal-db`,
+then refresh. This does not reset your baseline or database. A copied package does not
+track subsequent edits to the original checkout; do not bypass the containment check.
+
 Native Windows inspection refusal is not database-runtime support. Browser-based
 VS Code, Codespaces, SSH and Dev Containers have no end-to-end support claim.
 Native Windows means the Windows Node/extension host, not a Windows desktop
@@ -84,10 +92,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.21 release](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.21).
-Under **Assets**, download `rehearsal-db-0.1.21.vsix` and `SHA256SUMS`. In a terminal,
-run `shasum -a 256 /path/to/rehearsal-db-0.1.21.vsix` on macOS or
-`sha256sum /path/to/rehearsal-db-0.1.21.vsix` on Linux. Compare the result with that
+[Starter 0.1.22 release](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.22).
+Under **Assets**, download `rehearsal-db-0.1.22.vsix` and `SHA256SUMS`. In a terminal,
+run `shasum -a 256 /path/to/rehearsal-db-0.1.22.vsix` on macOS or
+`sha256sum /path/to/rehearsal-db-0.1.22.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.
@@ -153,6 +161,21 @@ paused. Use the local address shown by the owning terminal. **Open application**
 that address without running another CLI command. Press **Ctrl+C** once in the owning
 terminal when done, then wait for its shell prompt and the configured lifecycle result.
 
+An active command, a recorded completed/failed rehearsal and a database left running
+are separate states. **Database sandbox running** does not mean a rehearsal command
+is still executing. A database-only project can review migrations and **Verify** without
+configuring browser launch. A configured proof is not a passed proof: recorded success
+requires a completed primary application-proof stage and is historical, not a fresh
+verification of later edits. Missing, stale, failed or ambiguous evidence stays explicit.
+
+With core 1.0.2, **Activity & reports** retains bounded, safe explanations for recognized
+migration failures and their next steps after refresh. Unsupported provider evidence stays
+unknown. When exact PostgreSQL input provenance is available, the source action opens
+only the unchanged approved local migration; changed files or dirty buffers are refused.
+That link identifies submitted input, not a proven failing SQL origin or line/column.
+Supabase batch attribution may remain unknown. Follow the tutorial's reviewed correction
+and new candidate digest; the editor never rewrites or retries SQL automatically.
+
 ## Optional automatic updates
 
 Open **Rehearsal: Check for Updates** from the Command Palette, or use the dashboard's
@@ -199,7 +222,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.21/README.md#install-and-open-your-project).
+[installation guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.22/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
@@ -209,13 +232,15 @@ offline availability is not proof that you are up to date.
 
 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. User-approved package operations and external links
-may use their own services.
+baseline contents, or project source during passive inspection. 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.21 carries the same
-[free Starter license](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.21/LICENSE).
+Starter 0.1.22 carries the same
+[free Starter license](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.22/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.
@@ -224,17 +249,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.21/docs/commercial-readiness.md)
+[edition guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.22/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.21/PRIVACY.md)
-and [support policy](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.21/SUPPORT.md).
+read the release's [privacy statement](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.22/PRIVACY.md)
+and [support policy](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.22/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.21/SECURITY.md)
+Use its [private security process](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.22/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.0.1",
+  "version": "1.0.2",
   "private": false,
   "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
   "repository": {