feat(objects): edit a database object's definition and apply the DDL (#789)

docker/postgres-init/03-object-fixture.sql

@@ -30,3 +30,45 @@ CREATE TABLE IF NOT EXISTS public.orders (
 -- family applies no privilege check at all.
 DROP ROLE IF EXISTS src_probe;
 CREATE ROLE src_probe LOGIN PASSWORD 'src_probe';
+
+-- Phase 3 (#789). The object the READ BOUND actually bites, and its control.
+--
+-- Until this existed, the rule "a part carrying `truncated` is never editable" was a guard over an
+-- EMPTY POPULATION on every engine in the fleet: the Phase 1 and Phase 2 conformance fixtures were
+-- built short, docs/providers/postgres.md records definitions of 119 to 606 characters, and
+-- SOURCE_CHARACTER_LIMIT is 1,000,000. The browser probe built one of 1,275,140 characters by hand
+-- and it is the only truncation population that has ever existed for this engine.
+--
+-- A `DO` block that BUILDS the body rather than a 1.2 MB literal committed into an init script: the
+-- file stays small and the object is the same size every time.
+DO $fixture$
+DECLARE
+  filler text := repeat('-- padding for the object source bound, #789' || chr(10), 27000);
+BEGIN
+  EXECUTE 'CREATE OR REPLACE FUNCTION app.over_limit_fn(n integer) RETURNS integer LANGUAGE sql AS $body$' ||
+          chr(10) || filler || 'SELECT n;' || chr(10) || '$body$';
+END
+$fixture$;
+
+-- The CONTROL, just UNDER the bound. Without it the truncation assertion cannot distinguish "the
+-- bound bit" from "this object is large", which is the difference between a measurement and a
+-- coincidence. The browser probe measured the same shape at 975,134 characters.
+DO $fixture$
+DECLARE
+  filler text := repeat('-- padding for the object source bound, #789' || chr(10), 21000);
+BEGIN
+  EXECUTE 'CREATE OR REPLACE FUNCTION app.huge_fn(n integer) RETURNS integer LANGUAGE sql AS $body$' ||
+          chr(10) || filler || 'SELECT n;' || chr(10) || '$body$';
+END
+$fixture$;
+
+-- The ownership refusal's population, and the control that makes it non-vacuous (#789 Phase 3).
+--
+-- MEASURED on 18.4: these grants do NOT make the apply work, because `CREATE OR REPLACE` on
+-- somebody else's object is an OWNERSHIP check and not a privilege check. The refusal is
+-- `must be owner of function order_total`, SQLSTATE 42501, and the shipped error mapper turns it
+-- into an HTTP 500 because the message matches none of its substrings. The CONTROL is in the same
+-- session: this same role creating an object OF ITS OWN in this same schema succeeds, so the
+-- refusal is about ownership rather than about the schema or the role.
+GRANT USAGE ON SCHEMA app TO src_probe;
+GRANT CREATE ON SCHEMA app TO src_probe;

docs/API_DOCS.md

@@ -1,6 +1,6 @@
 # LibreDB Studio API Documentation
 
-> **Version:** 0.14.1
+> **Version:** 0.16.0
 > **Base URL:** `https://your-domain.com` or `http://localhost:3000`
 > **Content-Type:** `application/json`
 
@@ -789,6 +789,134 @@ A `druid` connection fails the second check whatever the `type` is, with `{ "err
 
 A `trino` connection passes it for `kill` and fails it for everything else, which is the difference between an empty supported set and a set of one: `CALL system.runtime.kill_query` really terminates a statement (verified end to end - the target then fails `ADMINISTRATIVELY_KILLED`), while vacuum, reindex, optimize, check and analyze all describe work that belongs to the connector behind a catalog rather than to the engine.
 
+#### POST /api/db/objects/edit-plan
+
+Build a plan for an edited object definition, and answer what an apply would send.
+It executes nothing and writes nothing.
+
+These two routes are the first object routes documented in this file at all.
+Their seven Phase 2 siblings under `/api/db/objects/` are not documented here yet.
+
+**Authentication:** Required.
+There is NO admin gate on either route, and the reason is measured rather than preferred: a
+`user`-role session already creates and drops routines through `POST /api/db/query`, so the role
+decides which connection may be OPENED and nothing about what may be done with it.
+A seed connection that the caller's role is not admitted to still answers `403`, unchanged, because
+both routes resolve the connection through the same seed filter every other database route uses.
+
+**Request:**
+```json
+{
+  "connection": { "id": "conn-123", "type": "postgres", "host": "localhost", "port": 5432, "database": "mydb", "user": "app" },
+  "path": ["app", "order_total(integer)"],
+  "kind": "function",
+  "partId": "definition",
+  "text": "FUNCTION app.order_total(integer) RETURNS integer LANGUAGE sql AS $$ SELECT 1 $$"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `connection` or `connectionId` | object or string | Yes | The same connection selector every database route takes |
+| `path` | string[] | Yes | The object's path, container segments first. An empty array is refused |
+| `kind` | string | Yes | The object kind id, as the CONNECTED provider declares it |
+| `partId` | string | Yes | Which part of the definition this text is. A package has more than one |
+| `text` | string | Yes | The reader's edited text for THAT part, at most 1,000,000 characters |
+
+**Response (200 OK), a build that planned:**
+```json
+{
+  "built": true,
+  "plan": { "planVersion": 1, "planId": "...", "issuedAt": "...", "connectionFingerprint": "...", "type": "postgres", "path": ["app", "order_total(integer)"], "kind": "function", "partId": "definition", "strategy": "guarded-atomic-batch", "unit": { "medium": "statement", "steps": [{ "text": "...", "language": "pgsql", "segments": [] }] }, "session": [], "revision": { "check": "guarded", "token": "...", "basis": "pg_proc.xmin", "scope": "server" }, "consequences": [] },
+  "preimage": { "text": "...", "language": "pgsql" },
+  "planToken": "<JWS>"
+}
+```
+
+`plan.unit` is the exact artifact the apply will send, byte for byte.
+`preimage` is the definition the build READ, for the preview's left side, and it rides in the
+response rather than inside the plan: a plan carrying both would be about 12 MB inbound on the
+apply and would be silently truncated by the framework at 10,485,760 bytes.
+`planToken` seals the plan; the apply refuses a plan whose bytes do not match the token it arrives
+with.
+The plan is readable and unforgeable, which are different properties: a client may read every field
+and may not change one.
+
+**Response (200 OK), a build that REFUSED:**
+```json
+{
+  "built": false,
+  "refusal": { "refusal": "privilege", "sentence": "must be owner of function order_total", "code": "42501", "at": { "within": "none" } }
+}
+```
+
+A deliberate engine refusal is a `200` carrying a typed verdict and never a `4xx` or a `5xx`.
+The request was well formed and was carried out; what the engine said is the payload.
+
+#### POST /api/db/objects/edit-apply
+
+Send a plan issued by `edit-plan`, and answer what the engine did.
+This is the only route in this product that writes a user's database object, and it is the first
+one whose action is recorded in the audit log.
+
+**Authentication:** Required. No admin gate, for the reason stated above.
+
+**Request:**
+```json
+{
+  "connection": { "id": "conn-123", "type": "postgres" },
+  "plan": { "planVersion": 1, "planId": "..." },
+  "planToken": "<JWS>",
+  "acknowledged": ["replaces-whole-container"]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `connection` or `connectionId` | object or string | Yes | Must resolve to the SAME server the plan was built against |
+| `plan` | object | Yes | The plan `edit-plan` answered, unchanged |
+| `planToken` | string | Yes | The token `edit-plan` answered beside it |
+| `acknowledged` | string[] | Only when the plan names consequences | One entry per `plan.consequences[].loses`. The check is enforced by the SERVER |
+
+**Response (200 OK):** one arm of the outcome union, always with a `duration` in milliseconds.
+
+| `outcome` | Meaning | Also carries |
+|-----------|---------|--------------|
+| `applied` | The addressed object was replaced and nothing else was destroyed | `revision` |
+| `applied-with-collateral` | Replaced, AND something the plan warned about was destroyed | `lost`, `revision` |
+| `applied-elsewhere` | The engine accepted the text and the addressed object is not what changed | `undone`, optional `wrote` |
+| `conflict` with `conflict: "object-changed"` | The object moved between the read and the write. Nothing was executed | `current`, for the diff |
+| `conflict` with `conflict: "engine-refused-concurrent"` | Refused on concurrency, not content. Nothing changed and the same plan may be sent again | `sentence`, optional `code` |
+| `refused` | The engine refused the write. Nothing changed | `refusal` |
+| `interrupted` | The statement was sent and no readable answer came back | `committed`, `sentence` |
+
+There is NO `retryable` field on this route at any status.
+A client that retries an apply whose disposition is unknown applies twice.
+Once the provider has been called, no error escapes as an HTTP error: a throw and an unreadable
+answer both become `interrupted` with `committed: "unknown"` at `200`.
+
+**Statuses, both routes:**
+
+| Condition | Status | Body |
+|-----------|--------|------|
+| Any DECIDED provider answer: a build that planned, a build that refused, and all seven apply outcomes | `200` | the typed union above |
+| Caller mistakes decided from the DECLARATION: undeclared kind, kind not editable, `path` not a path, missing `partId`, malformed plan, a build answering both a plan and a refusal, an unacknowledged required consequence | `400` | `{ "error": "..." }` |
+| Plan token invalid, expired, digest mismatch, wrong connection fingerprint, unknown `planVersion` | `400` | `{ "error": "...", "code": "EDIT_PLAN_INVALID" }` |
+| Body above 8,388,608 bytes, or `text` above 1,000,000 characters | `413` | `{ "error": "..." }` |
+| No session | `401` | `{ "error": "Authentication required" }` |
+| Seed connection not available for the caller's role | `403` | the existing `SeedConnectionError` body |
+| Rate limited | `429` | `{ "error": "...", "code": "RATE_LIMITED" }` |
+| A throw BEFORE the provider call | as `createErrorResponse` maps it | inherited |
+| Anything undeclared | `500` | `createErrorResponse`'s body |
+
+**Audit.**
+One apply emits exactly two `object_edit` events under one `correlationId`, which is `plan.planId`:
+a DECISION event with `action: "PLAN"` before the provider is called, and an OUTCOME event with
+`action` set to the plan's strategy after it.
+Neither event ever carries the statement, the command payload, the reader's text, the pre-image, the
+engine's message, the engine's code, the revision token or the plan token.
+A plan the seal refuses emits ONE event, with `reason: "object_edit_plan_invalid"`.
+
 ---
 
 ### AI API
@@ -1345,6 +1473,7 @@ interface ActiveSession {
 | `401` | Unauthorized - Missing or invalid authentication |
 | `403` | Forbidden - Insufficient permissions, or the request's Origin does not match this deployment (`ORIGIN_MISMATCH`) |
 | `408` | Request Timeout - Query exceeded time limit |
+| `413` | Payload Too Large - the request body, or one part's text, is above the object edit routes' own bound |
 | `429` | Too Many Requests - Rate limit exceeded. Applies to `POST /api/auth/login` and every session-guarded route (see "Rate Limiting" below), not only the AI endpoints |
 | `499` | Client Closed Request - Query cancelled by the client |
 | `500` | Internal Server Error |
@@ -1384,6 +1513,7 @@ These are the values of the `code` field emitted by `createErrorResponse` (`src/
 | `INTERNAL_ERROR` | Unhandled server error (500) |
 | `NETWORK_ERROR` | Network failure |
 | `RATE_LIMITED` | Application-level rate limit exceeded (429) - see "Rate Limiting" below |
+| `EDIT_PLAN_INVALID` | An object edit plan did not verify: forged, expired, digest mismatch, wrong connection fingerprint, or an unknown `planVersion` (400). Returned by the two `/api/db/objects/edit-*` routes directly rather than through `createErrorResponse`. It is a machine-readable code and not a sentence, so a client can tell a plan that no longer verifies apart from an apply that failed and offer to rebuild the preview; no shipped UI branches on it yet |
 
 The Origin-mismatch 403 (see "CSRF: Origin Check" below) is not in this table: it is returned
 directly by the request middleware (`src/proxy.ts`), before a request ever reaches