@rehearsal-db/core 1.1.0 → 1.3.0

package/docs/commands.md

@@ -3,6 +3,26 @@
 Run commands from the project directory containing `rehearsal.config.mjs`. The examples
 use `npx`, so a global install is not required.
 
+## Participating local workloads
+
+Core 1.3.0 and later builds advertising `rehearsalContracts.workloadQueue: 1` support
+`npx --no-install rehearsal workloads --json`. This read-only command needs no
+project configuration or Docker. Its version-1 `data` lists lifecycle ticket IDs,
+commands, PIDs, phases (`choosing`, `queued`, `held`), owner liveness and creation
+times. It reports `capacity: "not-measured"`: this is cooperative admission, not
+a claim about spare host/VM memory. Project paths, migration SQL and credentials
+are not included. Enable participation with
+[`resources.workloadQueue`](configuration.md#resource-review-policies).
+
+A dead holder blocks new admission until explicitly reviewed. Confirm its owned
+commands and descendants have ended before running
+`npx --no-install rehearsal workloads recover --confirm-workloads=<recoveryDigest>`.
+The exact inspection digest binds only the dead held records; changed records,
+missing confirmation and live owners refuse recovery. This operation clears local
+queue metadata only. It does not stop processes/containers or alter databases.
+Waiting requests can be cancelled; expiry never steals a live holder. Read-only
+inspection does not clean stale records or create state directories.
+
 ## Guided mode
 
 For editor-style review, `npx rehearsal inspect plan --json` returns a bounded,
@@ -10,6 +30,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, introduced in core 1.2.0, does not change
+`inspect plan` version 1. Older releases without the capability do not provide it.
+
+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 build advertising `rehearsalContracts.migrationImpact: 1` adds two free,
+optional commands, introduced in core 1.2.0. Check the installed capability rather
+than assuming an older release provides them. 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 +284,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 +513,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 +626,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,
@@ -368,7 +386,8 @@ inspection remain explicit command choices. See [CLI commands](commands.md).
 
 ### Resource review policies
 
-`resources` applies to the configured project topology, not the shared Docker engine:
+Resource review limits apply to the configured project topology, not the shared Docker
+engine. The optional workload queue instead coordinates participating local projects:
 
 ```ts
 resources: {
@@ -376,6 +395,7 @@ resources: {
   retainedEnvironmentCount: 2,
   maximumBytes: null,
   cleanupSchedule: "daily-preview",
+  workloadQueue: { enabled: true, waitTimeoutSeconds: 30 },
 },
 ```
 
@@ -392,6 +412,36 @@ resources: {
   shown on the next resource inspection. There is no daemon, operating-system scheduler,
   or automatic deletion. An approved cleanup records an owner-only, project/policy-bound
   review time; ordinary read-only inspection writes nothing.
+- `workloadQueue` is optional and off when omitted. With `enabled: true`, participating
+  Rehearsal clients serialize their `start`, `reset`, `run` and `migrate` runtime phases
+  across projects for the same local OS user, boot and process namespace. Waiting is
+  bounded to `waitTimeoutSeconds` (integer 0–300; default 30); zero refuses immediately
+  when busy. Ctrl+C cancels the waiting request without interrupting its holder.
+  Stop, discard, inspection and cleanup remain available. `open` releases admission
+  after startup, before its interactive session; application proofs run outside this
+  first lifecycle-only queue. This does **not** measure available RAM, stop existing
+  runtimes, limit other tools, or promise an entire Docker/VM memory budget. All projects
+  that should cooperate must opt in. Older clients and different OS users/namespaces do
+  not participate. Local filesystems with coherent atomic file operations are required;
+  this is not a network-filesystem or distributed scheduler.
+  Configure it in the source configuration for now; the existing editor field-metadata
+  contract is unchanged so older supported Starter clients keep working.
+
+Run `rehearsal workloads` (or `--json`) without Docker to inspect this queue. Waiting
+requests whose processes have died can be removed automatically because guarded work
+never began. A dead **holder** remains blocking: its child may still be running.
+After checking its owned commands and descendants, use the exact digest shown by
+inspection with `rehearsal workloads recover --confirm-workloads=<digest>`. Recovery
+removes only those reviewed dead-holder metadata records. It never kills a process,
+stops a container, removes data or treats age alone as permission to steal admission.
+Live owners cannot be recovered, even after a wait expires. Malformed or inaccessible
+state refuses admission; it is not silently deleted.
+
+Queue state is private to the local OS user under `~/Library/Application Support/Rehearsal`
+on macOS or `~/.local/state/rehearsal` on Linux/WSL, independent of `TMPDIR`. Advanced
+launchers can set `REHEARSAL_USER_STATE_DIRECTORY` to one absolute local directory;
+every cooperating client must use the same value. Do not delete or move active queue
+state. Boot/namespace-separated records are retained, not automatically pruned.
 
 Temporary files and application processes created by an operation are cleaned up by
 that operation's existing ownership boundary. These policies do not turn a persistent

package/docs/getting-started.md

@@ -15,7 +15,7 @@ They are readable helpers, not native executables or bundled Node/Docker install
 Existing Node.js 22, 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.1.0 install requires that version to
+before choosing an install option. The helper's exact target requires that version to
 be published; a checked-in helper is not proof of publication.
 
 ### Windows: use a WSL 2 Linux workspace

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
@@ -131,6 +133,10 @@ release-source migration.
 
 1. Start from protected `main` on a dedicated ticketed release branch.
 2. Verify the exact version, changelog, compatibility notes, and packed file list.
+   Reconcile the core, VS Code extension and Test Lab READMEs and affected guides with
+   their actual published versions and contracts. Keep candidate availability explicit,
+   link to the owning installation/update guide instead of duplicating version lists,
+   and retain dated historical evidence without presenting it as current acceptance.
 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

package/docs/roadmap.md

@@ -1,11 +1,13 @@
 # Next steps
 
-Rehearsal core **1.1.0 is available on
-[npm](https://www.npmjs.com/package/@rehearsal-db/core)** for guided Supabase and
-ordinary PostgreSQL migration rehearsals. The [free VS Code Starter 0.1.23 preview](vscode.md)
-adds a visual workbench and is distributed through Marketplace and reviewed GitHub
-VSIX releases. Neither requires a purchase or account. Core is MIT-licensed; all
-features included in Starter are free indefinitely for personal or commercial development.
+Rehearsal core is available on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core) for guided Supabase and
+ordinary PostgreSQL migration rehearsals. The [free VS Code Starter preview](vscode.md)
+adds a visual workbench through Marketplace and reviewed GitHub VSIX releases.
+[Releases and updates](updating.md) explains how to find and install the published
+versions; a roadmap or source version is not a publication claim. Neither requires
+a purchase or account. Core is MIT-licensed; all features included in Starter are
+free indefinitely for personal or commercial development.
 
 Stable core, the editor preview and a future paid Pro offer have separate completion
 boundaries. A downloadable preview does not imply that every native accessibility,
@@ -61,6 +63,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/stability.md

@@ -1,13 +1,13 @@
 # Stability and release verification
 
-Rehearsal core **1.1.0 is published** on
-[npm](https://www.npmjs.com/package/@rehearsal-db/core). This page defines its
+Stable Rehearsal core releases are available on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This page defines the
 compatibility promise and the verification policy for releases; it is not an
 unfinished launch checklist. Stable core does not require every planned database,
 editor interface, or paid feature.
 
 The compatibility promise began with **1.0.0**. The separate
-[VS Code Starter 0.1.23 preview](vscode.md) has its own editor acceptance and does
+[VS Code Starter preview](vscode.md) has its own editor acceptance and does
 not turn a core release into a completed accessibility or provider walkthrough.
 
 ## What becomes a compatibility promise
@@ -98,7 +98,7 @@ baseline. Automatic compatible updates do not cross the 0.x-to-1.x version bound
 review the changelog and deliberately select the stable version:
 
 ```bash
-npm install --save-dev --save-exact @rehearsal-db/core@1.1.0
+npm install --save-dev --save-exact @rehearsal-db/core@1.3.0
 npx --no-install rehearsal --version
 npx --no-install rehearsal doctor
 ```

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.3.0
+release only after it appears in the official registry:
+
+```bash
+npm install --save-dev --save-exact @rehearsal-db/core@1.3.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).