@rehearsal-db/core 1.0.1 → 1.1.0

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.23**, 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.23)
 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.
@@ -44,8 +44,8 @@ boundaries, baselines, migration digests, runtime isolation, locks, rollback, an
 Use desktop VS Code 1.101 or newer on macOS or Linux and a supported Node.js release
 (22, 24, or 26). You do not need the extension source repository or Test Lab.
 For a Windows desktop, use the [WSL 2 Linux-workspace setup](getting-started.md#windows-use-a-wsl-2-linux-workspace).
-With editor 0.1.21, native Windows inspection and foreground actions refuse before launching a child
-process and directs you to Remote-WSL. Install the extension into the Linux extension
+Since editor 0.1.21, native Windows inspection and foreground actions refuse before launching a child
+process and direct you to Remote-WSL. Install the extension into the Linux extension
 host and keep the project on its Linux filesystem. WSL compatibility remains a preview;
 real WSL core fixtures do not certify a native Remote-WSL editor walkthrough.
 
@@ -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.23**.
 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.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
 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.
@@ -139,6 +147,11 @@ reviewed change. Wait for **Saved**, then choose **Return to project**. Concurre
 refuse safely instead of overwriting someone else's work; a saved confirmation is tied
 to the exact bytes read back from disk, not merely a completed write request.
 
+Invalid structured fields show supported values or numeric limits before review.
+For example, retained environment count must be a whole number from 1 to 1000.
+If a review becomes stale, close it, refresh Rehearsal, and review the current source;
+saved and unsaved edits are not reverted. A refusal does not retry or reset a database.
+
 Commands reuse the same Rehearsal terminal for a project only after its previous command
 has a confirmed exit and its directory still matches. A running sandbox or manually
 entered foreground command is never interrupted to make room for another action. If
@@ -153,6 +166,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 +227,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.23/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 +237,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.23 carries the same
+[free Starter license](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.23/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 +254,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.23/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.23/PRIVACY.md)
+and [support policy](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.23/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.23/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.1.0",
   "private": false,
   "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
   "repository": {