@rehearsal-db/core 1.0.1 → 1.1.0

package/dist/src/targets/supabase_start_failure.mjs

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

package/docs/README.md

@@ -41,7 +41,7 @@ accomplish and follow that path.
 ## Follow the project
 
 - [Roadmap](roadmap.md)
-- [Stability and the first stable release](stability.md)
+- [Stability and release verification](stability.md)
 - [Repository architecture](architecture.md)
 - [Release process](releasing.md)
 

package/docs/architecture.md

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

package/docs/commands.md

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

package/docs/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
@@ -300,8 +304,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 +643,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.1 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/releasing.md

@@ -138,7 +138,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 +197,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,
@@ -48,6 +63,12 @@ consumer migrations. Record the observed results for each exact candidate separa
 
 ## 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`

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/troubleshooting.md

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