@rehearsal-db/core 1.0.2 → 1.2.0

package/docs/runtime-policies.md

@@ -66,6 +66,151 @@ identity policy. Verification accepts the configured placeholder before associat
 the exact recorded local identity afterward. Rehearsal stores that mapping only in its
 local internal schema; it does not duplicate the old role or weaken the row check.
 
+### Explicit Data API grants
+
+Supabase's [official announcement](https://supabase.com/changelog/45329-breaking-change-tables-not-exposed-to-data-and-graphql-api-automatically)
+sets October 30, 2026 for changing existing projects to opt-in exposure of new
+`public` tables. Existing table grants remain; this is not evidence that a particular
+project's setting has already changed. Direct PostgreSQL access is a separate contract.
+
+[Grants and RLS](https://supabase.com/docs/guides/api/securing-your-api) answer different
+questions: a grant allows an API role to reach an object; an RLS policy decides which
+rows that role can use. Passing an administrator SQL query or finding an RLS policy
+does not prove that an application's Data API request will work safely.
+
+For every new or recreated API table:
+
+1. Review the exposed schemas and the exact operations needed by `anon`,
+   `authenticated`, and `service_role`. An internal table does not need API access.
+2. Put explicit, least-privilege grants and RLS in that table's new migration. Remove
+   unwanted inherited defaults for the new object; do not blindly grant anonymous CRUD.
+   Check its sequences and callable functions separately, including `PUBLIC EXECUTE`.
+3. Preserve already-applied migration files. Correct historical objects through a
+   separately reviewed forward migration, not by rewriting the baseline's prefix.
+4. Test an empty setup and the disposable restore/reset/replay path with both permissive
+   and revoked automatic defaults. A schema dump alone is not proof of effective ACLs:
+   [Supabase's dump guidance](https://supabase.com/docs/reference/cli/supabase-db-dump#supabase-db-dump)
+   warns that target default privileges can broaden restored access.
+5. Independently check SQL grants, RLS and actual allowed/denied Data API requests with
+   the application's roles. A successful `service_role` request does not prove ordinary
+   authenticated access, and an empty RLS-filtered response is not a grant refusal.
+
+For example, a **new read-only authenticated API table**, created by its migration owner,
+can deliberately declare its own boundary:
+
+```sql
+create table public.api_notes (
+  id bigint generated by default as identity primary key,
+  owner_id uuid not null,
+  body text not null
+);
+alter table public.api_notes enable row level security;
+revoke all on table public.api_notes from public, anon, authenticated, service_role;
+revoke all on sequence public.api_notes_id_seq from public, anon, authenticated, service_role;
+grant select on table public.api_notes to authenticated;
+create policy read_own_notes on public.api_notes
+  for select to authenticated using ((select auth.uid()) = owner_id);
+```
+
+This example deliberately permits no client inserts, sequence use or service-role
+access. Choose a different reviewed boundary when the application needs those operations.
+Apply such SQL only through your own authorized migration process; Rehearsal does not
+change hosted grants or RLS on your behalf.
+
+### Read-only privilege expectations (core 1.1.0 and newer)
+
+Core 1.1.0 adds the following optional declaration. Earlier releases, including
+1.0.2, do not accept `privileges`; install a published release containing this contract
+before adding it. A project-owned application proof remains necessary for API/RLS behavior.
+
+Add `privileges` to the same runtime-policy JSON to check required and forbidden
+**effective** privileges after restore and migration. These checks issue no `GRANT`,
+`REVOKE`, role switch or permission repair. They do not infer grants from RLS.
+
+```json
+{
+  "policyVersion": 1,
+  "privileges": [
+    {
+      "kind": "schema",
+      "schema": "public",
+      "role": "authenticated",
+      "required": ["USAGE"],
+      "forbidden": ["CREATE"]
+    },
+    {
+      "kind": "table",
+      "schema": "public",
+      "name": "api_notes",
+      "role": "authenticated",
+      "required": ["SELECT"],
+      "forbidden": [
+        "INSERT",
+        "UPDATE",
+        "DELETE",
+        "TRUNCATE",
+        "REFERENCES",
+        "TRIGGER",
+        "MAINTAIN"
+      ]
+    },
+    {
+      "kind": "table",
+      "schema": "public",
+      "name": "api_notes",
+      "role": "anon",
+      "forbidden": [
+        "SELECT",
+        "INSERT",
+        "UPDATE",
+        "DELETE",
+        "TRUNCATE",
+        "REFERENCES",
+        "TRIGGER",
+        "MAINTAIN"
+      ]
+    }
+  ]
+}
+```
+
+Existing policy fields and structural/RLS expectations remain independent and compatible.
+Omitting `privileges` preserves the previous behavior; an empty array adds no checks.
+Each nonempty declaration needs at least one required or forbidden privilege. Omitted
+lists mean empty, but explicit `null`, overlapping lists, unknown fields and unsupported
+identifiers or privileges are rejected. At most 1,024 declarations are accepted.
+
+| Kind       | Object fields                     | Accepted privileges                                                                     |
+| ---------- | --------------------------------- | --------------------------------------------------------------------------------------- |
+| `schema`   | `schema`; no `name`               | `USAGE`, `CREATE`                                                                       |
+| `table`    | `schema`, `name`                  | `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, `REFERENCES`, `TRIGGER`, `MAINTAIN` |
+| `sequence` | `schema`, `name`                  | `USAGE`, `SELECT`, `UPDATE`                                                             |
+| `function` | `schema`, `name`, `argumentTypes` | `EXECUTE`                                                                               |
+
+Use exact uppercase privilege names and reviewed existing role/object names. Roles must
+exist in `pg_roles`; declare an actual application role to check access inherited from
+`PUBLIC`, not a standalone `PUBLIC` pseudo-role. Function checks cover ordinary functions,
+not procedures, aggregates or window routines. A function declaration must include its
+exact input types (including `INOUT`, excluding output-only arguments) as structured
+catalog names, for example
+`"argumentTypes": [{ "schema": "pg_catalog", "name": "uuid" }]`; `[]` selects a
+zero-argument function. At most 32 arguments are supported. SQL signature strings and
+non-`pg_catalog` argument types are not accepted; use a project-owned proof for unsupported
+signatures rather than changing a function to fit the check.
+
+Effective checks include inherited role permissions and grants through `PUBLIC`.
+Required table access means a full-table privilege. Forbidden `SELECT`, `INSERT`,
+`UPDATE` and `REFERENCES` also detect a privilege granted on only one column.
+`MAINTAIN` is checked on PostgreSQL 17 and newer; below 17 it is unavailable, so a required
+check fails and a forbidden check passes. Missing roles, objects, types or exact function
+signatures fail rather than being interpreted as a successful denial.
+
+These declarations do not inventory undeclared objects, prove RLS expressions or grant
+options, change Data API exposure settings, or make a live HTTP request. Keep your
+application's positive and negative API proof alongside them, including fresh setup and
+replay coverage. A failed check needs a fresh reviewed migration; it is never an
+automatic privilege escalation or a reason to use hosted administrator credentials.
+
 ## Identity policy
 
 The identity policy links one verified local Supabase identity to a copied pseudonymous

package/docs/stability.md

@@ -1,11 +1,15 @@
-# Stability and the first stable release
+# Stability and release verification
 
-Rehearsal core **1.0.0 is published** on
+Rehearsal core **1.1.0 is published** on
 [npm](https://www.npmjs.com/package/@rehearsal-db/core). This page defines its
 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
+not turn a core release into a completed accessibility or provider walkthrough.
+
 ## What becomes a compatibility promise
 
 Starting with `1.0.0`, Rehearsal treats these documented surfaces as public:
@@ -65,7 +69,7 @@ ready. The sequence below is policy, not a claim that its checks have passed.
    corrected candidate. Reuse sufficient unchanged evidence with its original scope;
    do not relabel old or unavailable manual checks as new results. No minimum number
    of calendar days replaces these checks.
-6. Publish `1.0.0` only when no blocking issue remains and the exact tarball has passed
+6. Publish the selected stable version only when no blocking issue remains and the exact tarball has passed
    the required release checks and consumer acceptance. The protected GitHub npm
    review is the single human authorization for its displayed exact version and
    checksum; no separate chat approval or pasted phrase is required.
@@ -94,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.0.0
+npm install --save-dev --save-exact @rehearsal-db/core@1.1.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.2.0
+release only after it appears in the official registry:
+
+```bash
+npm install --save-dev --save-exact @rehearsal-db/core@1.2.0
+npx --no-install rehearsal --version
+```
+
+Review the package and lockfile changes before the next Rehearsal command.
+
+## Breaking changes or known limitations?
+
+Check the target release notes before upgrading. Breaking upgrades, the move from a
+0.x preview to stable core, and local source/tarball installations need deliberate
+review rather than an automatic switch. See the [compatibility promise](stability.md#what-becomes-a-compatibility-promise)
+or [troubleshooting](troubleshooting.md) when an update is refused.
+
+Do not delete keys, baselines or sandbox data to update. Updating does not authorize
+production access or make an unsupported database or platform supported. Keep the
+[data-safety boundaries](security-model.md) and explicit reset/discard warnings in
+force; a successful rehearsal is not a guarantee that deployment is safe.
+
+## Where can I verify the package's origin?
+
+Use the official [npm package](https://www.npmjs.com/package/@rehearsal-db/core),
+[VS Code Marketplace listing](https://marketplace.visualstudio.com/items?itemName=rehearsal-db.rehearsal-db)
+or linked GitHub releases. npm provenance links the CLI package to its public release
+source and build. For a direct VSIX download, follow the [SHA-256 verification steps](vscode.md#direct-github-installation).
+Origin verification does not replace reviewing a release's compatibility or safety limits.
+
+You do not need publisher credentials, GitHub deployment approvals or the maintainer
+release checklist to install or update Rehearsal. Those belong to the
+[maintainer publishing guide](releasing.md).

package/docs/vscode.md

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

package/package.json

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