@rehearsal-db/core 1.0.2 → 1.2.0

package/docs/commands.md

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

package/docs/configuration.md

@@ -229,6 +229,10 @@ approval sequence.
 
 `runtimePolicy` replaces common restore adapters with reviewed schemas, allowlisted
 extensions, managed triggers, local-only singleton rows, and structural expectations.
+The [runtime policy guide](runtime-policies.md#explicit-data-api-grants) also owns the
+least-privilege Data API migration checklist and core 1.1.0's optional read-only
+required/forbidden privilege declarations. Earlier releases do not accept that new
+declaration. Rehearsal never infers or automatically grants API access.
 `identityPolicy` declares a hashed verified-email or provider-subject matcher, copied
 placeholder, safe signup defaults, required role/reference transfers, Storage path
 rewrites, and token checks. Provider credentials stay in the local Supabase runtime
@@ -285,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,
@@ -300,8 +322,10 @@ Rehearsal stacks.
 `keep-until-stop` preserves today's interactive behavior, while `stop-after-run` stops
 the targets after proofs, proof failures, or interruption. `lifecycle.open` uses
 `keep-until-stop` or `stop-on-application-exit` after the app closes. Every mode stops
-only Rehearsal's configured targets, never the shared engine. Ordinary stopping keeps
-database and Storage volumes and all sandbox edits; it does not reset or discard them.
+only Rehearsal's configured targets; lifecycle selection does not enable engine shutdown.
+The separately opted-in `stopOwnedColimaWhenIdle` policy above is the only guarded Colima
+shutdown path. Ordinary stopping keeps database and Storage volumes and all sandbox
+edits; it does not reset or discard them.
 See [Container runtime lifecycle](runtime-lifecycle.md).
 
 ### Foreground application idle shutdown
@@ -637,8 +661,17 @@ The VS Code Local Resources manager reviews an exact diff before changing either
 See [Local Resources](runtime-lifecycle.md#local-resources-manager) for image and volume rules.
 
 Use unique, non-privileged ports that do not overlap. `projectId` accepts lowercase
-letters, numbers, and hyphens. It labels the local Docker resources so cleanup targets
-only this project.
+letters, numbers, and hyphens: 2–40 characters for Supabase, or 2–63 for PostgreSQL.
+It labels the local Docker resources so cleanup targets only this exact project.
+Overlong configured IDs are refused before a provider starts; Rehearsal never truncates
+them or adopts resources using a shortened prefix. Review existing resources before
+changing a configured ID, and use a distinct reviewed identity for a new disposable
+runtime rather than assuming that a renamed config owns old containers or volumes.
+
+For new setup only, the generated `<project-name>-rehearsal` ID stays unchanged when it
+fits the selected provider. Longer new IDs use a readable prefix and a deterministic
+hash suffix within that provider's limit. Setup uses the same exact ID in the generated
+Rehearsal config and Supabase TOML. Existing configuration files are never rewritten.
 
 Application and readiness URLs must use a different port from the configured database,
 API, and Studio services. Editing a URL does not rewrite your framework's development

package/docs/getting-started.md

@@ -12,17 +12,17 @@ Separate setup folders are available for
 [macOS](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/macos) and
 [Linux](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/linux).
 They are readable helpers, not native executables or bundled Node/Docker installers.
-Existing Node.js 24 or 26 is required. The default only checks an existing project;
+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.0.2 install requires that version to
+before choosing an install option. An exact core 1.1.0 install requires that version to
 be published; a checked-in helper is not proof of publication.
 
 ### Windows: use a WSL 2 Linux workspace
 
 The Windows compatibility route is Linux execution inside **WSL 2**, not a native
-PowerShell/Command Prompt database runtime. Core 1.0.1 and extension 0.1.21 make that
-boundary explicit; native Windows version/help/discovery do not authorize runtime work.
+PowerShell/Command Prompt database runtime. Since core 1.0.1 and extension 0.1.21, that
+boundary is explicit; native Windows version/help/discovery do not authorize runtime work.
 
 1. Follow Microsoft's [WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install)
    to prepare a WSL 2 Linux distribution, such as Ubuntu 24.04. Do not use WSL 1.

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
@@ -138,7 +140,9 @@ release-source migration.
 4. When an unfamiliar developer is available, have them follow clean-project onboarding.
    Correct and retest the first confusing, missing, or wrong instruction. Record when
    this human observation was unavailable; automated checks must not impersonate it.
-5. Change `private` to `false` only in the reviewed release change.
+5. Confirm package metadata keeps `private: false` for this public npm package. Any
+   metadata change belongs in the reviewed release change; do not toggle visibility
+   or package privacy as an incidental publishing step.
 6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
    executable, declared runtime dependency inventory, and dependency audit result.
 7. Review the release change and its exact artifact evidence.
@@ -195,7 +199,7 @@ This is mutual exclusion, not a guaranteed ordered queue: reconcile a superseded
 pending workflow before deliberately requesting another run.
 
 The objective promotion checklist and compatibility boundary live in
-[Stability and the first stable release](stability.md).
+[Stability and release verification](stability.md).
 
 The trusted publisher allows `npm dist-tag` only so this workflow can maintain those two
 tags without a stored npm token. A manual workflow run from `main` can repair the correct

package/docs/roadmap.md

@@ -1,9 +1,16 @@
 # Next steps
 
-Rehearsal core **1.0.0 is available on
+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 preview](vscode.md)
-adds a visual workbench. Neither requires a purchase or account.
+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.
+
+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,
+provider or real-user acceptance observation has been completed. Publication does not
+authorize a new database operation or migrate a running legacy extension.
 
 The standalone workflow keeps the rehearsal engine in the package while application
 meaning and privacy decisions remain project-owned. The sequence below explains its
@@ -30,10 +37,18 @@ Track the full breakdown in
 For questions or feature requests, use
 [GitHub issues](https://github.com/Ddupasquier/rehearsal-db/issues).
 
-## Acceptance still required
+## Verification and supported-journey work
+
+The [release verification policy](stability.md) owns promotion requirements. The
+[Environment Workbench epic](https://github.com/Ddupasquier/rehearsal-db/issues/130)
+and its children track remaining editor acceptance; the issue tracker owns current
+status and pickup order, not this page. Supported-journey compatibility work,
+including the [Supabase grant-preservation review](https://github.com/Ddupasquier/rehearsal-db/issues/199),
+is distinct from adding new database families or paid features.
 
-These are verification requirements, not a live checklist of unfinished releases or
-consumer migrations. Record the observed results for each exact candidate separately.
+For each exact candidate, retain the checks already proved and complete the missing
+observations. The following describe evidence boundaries, not a claim that a shipped
+release or consumer upgrade remains unfinished:
 
 - Install the exact packed candidate in clean Supabase and PostgreSQL consumers.
 - Exercise two unrelated synthetic schemas, bounded large data, interruption, drift,
@@ -46,8 +61,33 @@ consumer migrations. Record the observed results for each exact candidate separa
 - 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
 
-After the PostgreSQL family is stable in real projects, evaluate individual PostgreSQL
-services. MySQL, MongoDB, and unrelated database families require different migration,
-restore, and safety behavior and remain out of scope.
+Additional database, runtime, identity-provider and migration-tool integrations require
+their own reviewed capability contracts and independent acceptance. Research or a roadmap
+ticket is not a support claim. MySQL, MongoDB, SQLite and other database families are not
+supported by this PostgreSQL/Supabase release. They remain separate future work rather
+than prerequisites for the current local workflow.
+
+The complete CLI and its database/safety capabilities stay free. Optional paid Pro
+workflows, licensing and commercial readiness remain separate owner decisions; this
+roadmap does not approve a paywall, price, billing service or new distribution operation.

package/docs/runtime-lifecycle.md

@@ -27,8 +27,8 @@ then repeat the command.
 
 Setting `autoStartColima: true` is an explicit convenience opt-in. If Docker is
 unavailable and the `colima` command exists, Rehearsal runs plain `colima start` and
-reports it. Rehearsal does not resize Colima and does not stop the shared engine
-automatically. Starting Docker can also wake unrelated containers that use Docker's
+reports it. Rehearsal does not resize Colima. Engine shutdown remains off unless the
+separate ownership-guarded policy below is explicitly enabled. Starting Docker can also wake unrelated containers that use Docker's
 `always` or `unless-stopped` restart policy. Rehearsal changes only the selected
 Supabase stack to Docker's `no` restart policy after it starts successfully.
 
@@ -84,8 +84,9 @@ lifecycle: {
 `run` accepts `keep-until-stop` or `stop-after-run`. `open` accepts
 `keep-until-stop` or `stop-on-application-exit`. The bounded choices stop every
 configured Rehearsal target in reverse dependency order after the command finishes,
-fails after startup, times out, or is interrupted. They never stop the shared Docker
-engine.
+fails after startup, times out, or is interrupted. Lifecycle choices govern targets,
+not engine ownership; they do not enable Colima shutdown. The separate
+`stopOwnedColimaWhenIdle` policy still requires its own opt-in and ownership checks.
 
 Stopping is non-destructive: database and Storage volumes, applied migrations, and
 sandbox edits remain available to `start` or `open`. Only the existing explicit `reset`
@@ -190,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