@dalgo/dalgo2postgrest 0.0.0-bootstrap.0 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Strongo Team
+Copyright (c) 2026 DALgo contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

package/README.md

@@ -1,5 +1,405 @@
-# @dalgo/dalgo2postgrest — bootstrap placeholder
+# DALgo adapter for PostgREST
 
-This prerelease only establishes the package identity for CI trusted publishing.
-It contains no adapter implementation, runtime entry point, scripts or dependencies.
-Use the later normal release published by dal-go/dalgo-http-adapters instead.
+`@dalgo/dalgo2postgrest` is a deliberately bounded, dependency-free TypeScript
+adapter from [`@dalgo/core`](https://github.com/dal-go/dalgo-js) to exposed
+PostgREST tables or updatable views. It uses the platform `fetch` API only. It
+does not call PostgreSQL directly, an administration endpoint, RPC, or resource
+embedding. A read-only discovery surface uses the OpenAPI document PostgREST
+already serves for the request role.
+
+## Security and browser boundary
+
+Pass an HTTPS `baseUrl` without credentials and a `headers` provider. HTTPS is
+the default and the only option for a hosted origin. Plain HTTP is accepted
+only for `localhost`, `127.0.0.1` or `[::1]`, and only with the explicit
+`allowInsecureLoopbackHttp: true` development option.
+
+The header provider runs for every HTTP request, allowing the application to
+obtain a fresh, narrowly scoped Bearer token or cookie from its own
+authenticated token broker. The adapter neither retains nor logs those values.
+Never put database credentials or access tokens in a URL, source control,
+analytics, browser storage, or an error report. Do not install a service-role
+or other administration key in a browser.
+
+Supabase is PostgREST. A browser example uses its publishable/anon `apikey`
+plus a **least-privilege user bearer** from the application's own token broker:
+
+```ts
+const db = new PostgrestDatabase({
+  baseUrl: "https://project.supabase.co/rest/v1",
+  headers: async () => ({
+    apikey: publicAnonKey, // publishable key, not a service-role key
+    authorization: `Bearer ${await getFreshUserAccessToken()}`,
+  }),
+});
+```
+
+PostgREST authenticates the JWT and performs authorization in the database.
+Configure token audience, role grants, row-level security, CORS
+origin/method/header allowlists, cookie policy, and proxy boundaries for the
+deployment. Direct browser access is an application decision; this package
+cannot make an overly broad CORS policy or a token with the wrong audience safe.
+The package source is browser-safe and imports no Node built-in.
+
+## Install
+
+`@dalgo/core` and `@dalgo/adapter-runtime` are peers. This package is not yet
+published to npm. First-wave consumers pin a reviewed commit of this monorepo as
+a pnpm Git subdirectory dependency, the same pattern used by
+`@dalgo/sqlite-wasm`.
+
+Each `github:` subdirectory dependency is fetched as its own workspace copy, and
+only that copy is prepared. The package's `prepack` therefore builds
+`@dalgo/adapter-runtime` from the same commit before type-checking itself; a
+separate prebuilt runtime tarball or a local workspace link is not required.
+Substitute the full 40-character SHA of the reviewed merged commit for
+`<merged-sha>` in every place below:
+
+```jsonc
+// package.json
+"@dalgo/core": "github:dal-go/dalgo-js#99165e9e1a39c32abee2b39d6395677843bc3559",
+"@dalgo/adapter-runtime": "github:dal-go/dalgo-http-adapters#<merged-sha>&path:/packages/adapter-runtime",
+"@dalgo/dalgo2postgrest": "github:dal-go/dalgo-http-adapters#<merged-sha>&path:/packages/postgrest"
+```
+
+```yaml
+# pnpm-workspace.yaml: pnpm blocks build scripts until each exact package is approved
+allowBuilds:
+  '@dalgo/core@https://codeload.github.com/dal-go/dalgo-js/tar.gz/99165e9e1a39c32abee2b39d6395677843bc3559': true
+  '@dalgo/adapter-runtime@https://codeload.github.com/dal-go/dalgo-http-adapters/tar.gz/<merged-sha>#path:/packages/adapter-runtime': true
+  '@dalgo/dalgo2postgrest@https://codeload.github.com/dal-go/dalgo-http-adapters/tar.gz/<merged-sha>#path:/packages/postgrest': true
+```
+
+If an entry is missing, pnpm names the exact key it needs; approve only the
+reviewed dependency, never a wildcard. From this repository,
+`pnpm check:git-subdir-consumer` installs these three packages from a temporary
+Git repository in a clean consumer and requires a strict typecheck, a dynamic
+import of every entry point, exactly one `@dalgo/core` `0.7.4` instance, no
+`@dal-go/dalgo`, and no local links. Run the identical check against a pushed
+commit with
+`DALGO_ADAPTER_GIT_SUBDIR_REF=github:dal-go/dalgo-http-adapters#<sha> pnpm check:git-subdir-consumer`.
+
+The `@dalgo/core` peer range is `>=0.7.4 <0.9.0`; the workspace tests against the
+exact `0.7.4` commit the web UI pins, so the browser contains one `Key`/query
+identity. From the repository root, `pnpm install --frozen-lockfile` and
+`pnpm --filter @dalgo/dalgo2postgrest check` run the workspace gate.
+
+## Minimal setup
+
+```ts
+import { collection } from "@dalgo/core";
+import { PostgrestDatabase } from "@dalgo/dalgo2postgrest";
+
+const db = new PostgrestDatabase({
+  baseUrl: "https://api.example.com/rest/v1",
+  headers: async () => ({ authorization: `Bearer ${await getFreshPostgrestToken()}` }),
+});
+
+const items = collection<{ title: string; done: boolean }>("items");
+await db.insert(items.key("milk"), { title: "Buy milk", done: false });
+```
+
+The type-checked version is [examples/basic.ts](examples/basic.ts). This maps
+the top-level DALgo collection `items` to the exposed `items` relation and its
+DALgo key ID to the relation's `id` column. Use `relationName` and `idColumn`
+when the schema uses different names. The relation must have a primary key or
+unique constraint suitable for PostgREST upsert, and the supplied identity must
+have only the needed database permissions.
+
+Use `schema` (or its `profile` alias) to select a PostgREST profile explicitly.
+The adapter sends `Accept-Profile` on reads and `Content-Profile` on writes.
+Profile selection never changes the configured `idColumn` or `relationName`
+mapping, and no profile is guessed from OpenAPI metadata.
+
+## Discovery and connection preflight
+
+`discover()` reads the root OpenAPI document with the same refreshed headers and
+caller cancellation as every other request. It returns only what the document
+actually declares, bounded by relation count, fields per relation, document
+bytes and local `$ref` depth. Remote `$ref` documents are never fetched.
+
+```ts
+import { POSTGREST_READ_CAPABILITIES, PostgrestDatabase } from "@dalgo/dalgo2postgrest";
+
+const db = new PostgrestDatabase({ baseUrl, headers });
+const status = await db.testConnection(controller.signal);
+
+if (status.ok) {
+  const discovery = await db.discover(controller.signal);
+  for (const relation of discovery.relations) {
+    console.log(relation.name, relation.fields, relation.primaryKey, relation.adapterQueryable);
+  }
+}
+
+const discoveryCapability = POSTGREST_READ_CAPABILITIES.query.discovery;
+```
+
+`discover()` never returns an empty relation list as if it were proof of an
+empty database. A denied identity, a disabled/missing OpenAPI endpoint, a
+malformed document, and a role with no visible relations are reported as
+`status: "unavailable"` with an explicit `reason` (`unauthorized`, `forbidden`,
+`metadata-disabled`, `metadata-malformed`, `request-failed`, or
+`no-relations`). `testConnection()` maps that to a UI-safe status and does not
+echo a response body, header, token, or transport error.
+
+Field types, formats, array item types, enums and primary-key markers appear
+only where the OpenAPI document declares them. A field whose type is expressed
+by an unresolvable/remote `$ref` is marked `typeStatus: "unavailable"`. The
+configured `idColumn` is shown per relation as `idColumn`, and
+`adapterQueryable` says whether this adapter can address the relation with the
+configured mapping. This is read-only discovery, not an administration API.
+
+Primary-key markers are collected from the complete declared property set, not
+from the bounded `fields` list, so a truncated field projection cannot turn a
+composite key into a false single-column key. `idColumn.uniqueStatus` separates
+three cases: `declared-primary-key` (the complete declared key is exactly that
+one column), `configured-contract` (the role's metadata declares no key, so the
+adapter relies on the caller's configured uniqueness contract), and
+`not-unique` (a different or composite key is declared, so the configured
+column alone cannot address one row, a stable keyset boundary, or a per-row
+write). `adapterQueryable` is `false` for `not-unique`; `readable` is separate
+provider authorization and never proves uniqueness or pagination stability.
+
+## Supported DALgo surface
+
+| DALgo operation | PostgREST mapping |
+| --- | --- |
+| `get` | Bounded `GET /relation?id=eq.value&limit=1`; an empty result is a missing snapshot. |
+| `getMany` | Ordered, bounded, bounded-parallel point reads. |
+| `insert` | `POST /relation` with an adapter-owned ID column; HTTP 409 becomes `AlreadyExistsError`. |
+| `set` | Single-row `PUT /relation?id=eq.value` with the complete payload; exactly one returned row is required. |
+| `update` | `PATCH /relation?id=eq.value` with strict `max-affected=1`; an empty returned representation becomes `NotFoundError`. |
+| `delete` | `DELETE /relation?id=eq.value` with strict `max-affected=1`; an empty returned representation is an idempotent missing delete. |
+| `query` | Legacy direct top-level relation `GET` with PostgREST filters, ordering, bounded `limit`, and `offset`; DALgo cursors are still refused. |
+| `queryWithSignal` | The same query with caller cancellation, one end-to-end deadline, and optional opaque keyset cursor continuation. |
+
+The adapter-owned ID column is removed before codec decoding. Consequently,
+codec-encoded record data must not contain that column. Query records construct
+top-level DALgo keys from its value. This is the **native-rows** storage mode:
+the adapter reads existing relations and never rewrites them into a DALgo
+envelope. Numeric, `null`, boolean and string values remain as PostgREST
+returned them; no projection is silently applied.
+
+## Cursor pagination
+
+`queryWithSignal()` returns `nextCursor` for every non-empty page, including a
+page shorter than the requested limit. A short page is not proof of
+end-of-data: PostgREST's `db-max-rows` (or a proxy) can cap every response below
+the requested `limit`. Pass the token back as `startAfter(...)` until a request
+returns an empty page. The cursor is opaque base64url and binds:
+endpoint, DALgo collection and exposed relation, configured profile and
+`idColumn`, filters, effective order, `select=*`, page size, and an optional
+non-secret `identityScope`. A cursor from another endpoint, relation, query,
+order, page size or identity scope is rejected with `PostgrestCursorError`
+(which is also an `UnsupportedError`) before HTTP.
+
+```ts
+const pageSize = 25; // adapter page, not a semantic total
+let cursor: string | undefined;
+do {
+  const builder = items.query().where("done", "==", false).orderBy("priority").limit(pageSize);
+  const page = await db.queryWithSignal(
+    cursor === undefined ? builder.build() : builder.startAfter(cursor).build(),
+    controller.signal,
+  );
+  render(page.records);
+  cursor = page.nextCursor?.values[0] as string | undefined;
+} while (cursor !== undefined);
+```
+
+The effective order always ends in the configured primary key, so a stable page
+has a deterministic tie-breaker even when the user order is not unique. The
+adapter uses keyset continuation (`or=(...)`), not a full scan and not
+`Prefer: count=exact`. Every non-empty page, short or full, may advertise a
+possible next page; the follow-up request that finds no rows ends pagination
+honestly with `{ records: [] }` and no cursor. A consumer that needs a bounded
+total stops after its own budget or the empty page.
+
+Legacy `query()` keeps its one-request `limit`/`offset` contract and never
+returns a cursor; a short legacy page is returned as-is.
+
+Two limits are intentionally different:
+
+- **Adapter page limit**: `maxQueryLimit` (default 100, hard maximum 1,000) is
+  the largest number of rows in one provider request/page.
+- **DataTug logical total/query limit**: a consumer/UI concern. The adapter does
+  not compute, cache, infer or guarantee a semantic total. Use explicit
+  continuation until the empty page, or the consumer's own bounded total.
+
+Offsets remain available for both legacy `query()` and `queryWithSignal()` and
+are bounded by `maxQueryOffset`. Cursor and offset cannot be combined. Cursor
+pages are bounded by `maxQueryPages`; a cursor that exceeds that bound is
+refused explicitly rather than silently restarting. Cursor metadata is bounded
+by `maxCursorBytes`.
+
+## Cancellation and capability admission
+
+```ts
+import { QueryCancelledError } from "@dalgo/adapter-runtime";
+import { POSTGREST_READ_CAPABILITIES, PostgrestDatabase } from "@dalgo/dalgo2postgrest";
+import { collection } from "@dalgo/core";
+
+const capabilities = POSTGREST_READ_CAPABILITIES;
+const built = collection<{ done: boolean }>("items").query().orderBy("done").limit(25).build();
+if (capabilities.query.sort.status === "unsupported" && built.orders.length > 0) {
+  throw new Error("PostgREST does not support ordering");
+}
+
+const controller = new AbortController();
+try {
+  const page = await db.queryWithSignal(built, controller.signal);
+  return page;
+} catch (error) {
+  if (error instanceof QueryCancelledError) {
+    // error.reason is "caller" or "deadline"; no token or abort reason leaks.
+    return undefined;
+  }
+  throw error;
+}
+```
+
+The caller signal covers header acquisition, `fetch`, response-body reading and
+cursor preparation. The adapter combines it with the configured `timeoutMs`
+(15 seconds by default, maximum 120) as one end-to-end deadline. A pre-aborted
+signal does no header or HTTP work; a late response body is cancelled and a late
+result is never returned. `queryWithSignal` rejects with `QueryCancelledError`
+for caller abort/deadline and with the existing redacted
+`PostgrestRequestError` for header/fetch/body transport failures. Deliberate
+query/unsupported errors are raised before any request and keep their messages.
+Legacy `query` keeps its interface and success behaviour.
+
+### Capability rows
+
+| Feature | Status | Bound / reason |
+| --- | --- | --- |
+| read/get, read/getMany | native | `getMany` max 100 keys, 8 parallel reads by default |
+| projection | unsupported | core `StructuredQuery` has no projection; `select=*` is always used and no field is dropped |
+| filter | native | simple column identifiers or `DOCUMENT_ID`; all DALgo operators; null only for `==`/`!=` |
+| sort | native | `asc`/`desc` on simple column identifiers; `queryWithSignal` adds the primary-key tie-breaker |
+| pagination | native | bounded `limit`/`offset`; opaque keyset cursor in `queryWithSignal`; legacy `query` refuses cursors |
+| joins, aggregation, grouping, subquery, fulltext, timeseries | unsupported | refused before HTTP |
+| native query | unsupported | no raw PostgREST parameters, embedding or RPC |
+| discovery | native | read-only bounded OpenAPI; role visibility and denied/disabled metadata are explicit |
+| bounds | enforced | query limit 100/1000, offset 100k/10M, pages 10k/1M, cursor 8KiB/64KiB, request/response 1 MiB/16 MiB, discovery 512KiB/16MiB, 100/10k relations, 200/10k fields, depth 4/16 |
+
+The exported constant is `POSTGREST_READ_CAPABILITIES`; `storage` is
+`"native-rows"` and `bounds` contains the constructor default and hard maximum
+for each numeric limit, including the PostgREST-specific discovery and cursor
+bounds.
+
+## Intentional limitations
+
+- DALgo callback transactions are rejected. PostgREST executes each HTTP
+  request in its own database transaction, so this package cannot honestly
+  provide an atomic, retryable callback across requests.
+- Nested DALgo keys, nested-collection queries, and collection-group queries
+  are rejected. A relation is one top-level DALgo collection, not a hierarchy.
+- Projection cannot be expressed through the current core `StructuredQuery`;
+  the adapter does not pretend it is supported. Discovery exposes field
+  metadata, while row reads always select `*`.
+- Supported filters are equality/inequality, comparisons, `in`, `not-in`, and
+  PostgreSQL-array containment/overlap; relation and field names are limited to
+  simple SQL identifiers. No resource embedding, JSON paths, full-text search,
+  aggregates, RPC, or server management API is exposed. A string used with a
+  single-value operator (`eq`, `neq`, `lt`, `lte`, `gt`, `gte`) is sent raw,
+  because PostgREST compares that operand literally and would include the
+  double quotes otherwise. Strings in a membership list (`in`, `not-in`) or an
+  array literal (`cs`, `ov`) are quoted and escaped, which is the documented
+  reserved-character context.
+- Reserved PostgREST control parameters (`select`, `columns`, `on_conflict`,
+  `order`, `limit`, `offset`, `and`, `or`) are quoted when they are used as
+  filter keys, order fields, or the configured `idColumn`, using PostgREST's
+  documented identifier quoting. Appending them unquoted would let PostgREST
+  consume the predicate as its own control and silently drop it. Names that
+  merely resemble a control (`order_id`, `limiters`, `ordinary`) stay unquoted
+  and keep working.
+- JSON numbers are checked against the raw response text before `JSON.parse`.
+  A number literal is accepted only when the decimal value it denotes is the
+  exact decimal value the adapter would serialize back. A high-precision
+  decimal such as `0.10000000000000001`, an exponent token that underflows to
+  zero (`1e-400`) or overflows to a non-finite value (`1e400`), `-0`, and any
+  integer (including an integer-valued decimal or exponent) outside the
+  lossless JavaScript safe range are refused with a redacted error before any
+  record or cursor is emitted. Canonical decimals such as `0.1`,
+  `0.30000000000000004` or `1.0`/`1e0` remain supported because their
+  serialized literal preserves the same decimal value. Outgoing filter,
+  record and cursor values are checked the same way. This prevents an ID such
+  as `9007199254740993` from becoming `9007199254740992`, and a keyset boundary
+  such as `0.10000000000000001` from being sent as `0.1`, which could repeat
+  the same actual numeric row.
+- `set` is full replacement, not merge-upsert: the supplied DALgo value is the
+  complete replacement record (apart from the adapter-owned ID). Fields omitted
+  from it are not sent for merge. PostgREST must expose a relation for which its
+  documented single-row `PUT` semantics are available.
+- `update` and `delete` ask PostgREST for `handling=strict, max-affected=1`
+  and verify returned cardinality. `set` verifies one returned `PUT` row;
+  PostgREST documents `max-affected` for PATCH and DELETE, not PUT.
+- PostgREST errors may contain database details and row values. Response bodies
+  are cancelled and discarded for non-2xx replies; `PostgrestHttpError` exposes
+  only the HTTP status. Header-provider, fetch, redirect, timeout, body-stream,
+  and JSON failures become a generic `PostgrestRequestError`, never their
+  original text. Inserts request `return=minimal` and cancel any unexpected
+  response body; keyed writes read a bounded representation to prove their
+  cardinality. Cancellation is best-effort and never awaited, so a hostile or
+  broken stream cannot outlive the request deadline.
+- Cursor pagination assumes the configured primary-key column is non-null and
+  unique. Discovery reports whether that is declared (`declared-primary-key`)
+  or relies on the configured contract (`configured-contract`). When metadata
+  declares a different or composite key, `uniqueStatus` is `not-unique` and
+  `adapterQueryable` is false: the adapter does not promise a unique key or
+  stable cursor boundary. A relation without a declared key can still be read
+  by key and offset, but that is the caller's uniqueness contract.
+- Discovery reflects the OpenAPI document for the current role at the time of
+  the request. It can lag a schema-cache reload, and it is not a grant of read
+  access to every advertised relation.
+
+## Official PostgREST references
+
+- [Tables and Views](https://docs.postgrest.org/en/stable/references/api/tables_views.html)
+- [Pagination and Count](https://docs.postgrest.org/en/stable/references/api/pagination_count.html)
+- [OpenAPI](https://docs.postgrest.org/en/stable/references/api/openapi.html)
+- [Prefer Header](https://docs.postgrest.org/en/stable/references/api/preferences.html)
+- [Schemas](https://docs.postgrest.org/en/stable/references/api/schemas.html)
+- [Authentication](https://docs.postgrest.org/en/stable/references/auth.html)
+- [Errors](https://docs.postgrest.org/en/stable/references/errors.html)
+
+## Verification
+
+`pnpm check` runs ESLint, deterministic Vitest HTTP-contract tests, declaration
+build, and type checks of the minimal example. The unit suite injects `fetch`
+for protocol/error/bound coverage. `test/node-http-transport.test.ts` is a Node
+HTTP contract test only: Node does not enforce browser CORS and the test sets
+`Origin` manually, so it does not prove browser behaviour.
+
+`pnpm test:browser` owns a second disposable Compose project named
+`datatug-postgrest-ts-r2-<run>` and a unique loopback static origin. It first
+builds the workspace dependency outputs (`@dalgo/adapter-runtime` among them),
+so it works from a clean source checkout, then builds the fixture page with
+esbuild, launches real headless Chromium through Playwright, and has the
+browser bundle use the real `PostgrestDatabase` and
+global `fetch` against that real PostgREST service. The service allows exactly
+the static page origin. The suite proves successful discovery, native rows and
+multi-page continuation across server-capped short pages, a redacted bad
+credential, an actual browser CORS refusal from a different origin, and caller
+abort. It does not intercept any PostgREST response. It removes only its own
+Compose project and fixture directory.
+
+`pnpm test:real` owns one disposable Docker Compose project named
+`datatug-postgrest-ts-<run>`, uses cached `postgrest/postgrest:v16.5` and
+`postgres:17` images, random loopback host ports, a synthetic JWT role, a
+read-only role, native seeded rows, `db-max-rows=2` below the requested page
+size, and exact-origin CORS. It runs the real PostgREST discovery, short-page
+cursor journey, changed/foreign cursor, bad-auth, read-only denial, no-relations
+and controlled-header tests, then removes only its own project and temporary
+files. Neither real-service suite proves a hosted Supabase deployment, its RLS
+policies, a gateway, or DataTug's actual connection form and UI journey; those
+remain separate acceptance gates for the owning application.
+
+`pnpm check:packed-consumer` (repository root) additionally packs the published
+artifacts into a fresh directory outside the repository, installs only those
+tarballs plus the exact modern `@dalgo/core` commit, and type-checks and runs the
+packed declarations with no `@dal-go/dalgo` package available.
+
+## License
+
+MIT

package/dist/capabilities.d.ts

@@ -0,0 +1,129 @@
+import type { AdapterReadCapabilities, NumericCapabilityBound, QueryCapabilityBounds } from "@dalgo/adapter-runtime";
+/** PostgREST-specific bounds in addition to the shared adapter capability shape. */
+export interface PostgrestQueryBounds extends QueryCapabilityBounds {
+    readonly maxQueryOffset: NumericCapabilityBound;
+    readonly maxQueryPages: NumericCapabilityBound;
+    readonly maxDiscoveryRelations: NumericCapabilityBound;
+    readonly maxDiscoveryFieldsPerRelation: NumericCapabilityBound;
+    readonly maxDiscoveryBytes: NumericCapabilityBound;
+    readonly maxCursorBytes: NumericCapabilityBound;
+    readonly maxSchemaDepth: NumericCapabilityBound;
+}
+export interface PostgrestCapabilityDescriptor extends Omit<AdapterReadCapabilities, "bounds"> {
+    readonly bounds: PostgrestQueryBounds;
+}
+/**
+ * Honest read/query capabilities of the PostgREST adapter.
+ *
+ * It reads existing exposed relations and never rewrites rows into a DALgo
+ * envelope. Discovery is a bounded read of the OpenAPI document generated for
+ * the request role; it is not an administration API and not a promise that the
+ * role can read every advertised relation. Core `StructuredQuery` has no
+ * projection field, so projection is explicitly unsupported rather than
+ * silently ignored.
+ */
+export declare const POSTGREST_READ_CAPABILITIES: {
+    readonly adapter: "@dalgo/dalgo2postgrest";
+    readonly storage: "native-rows";
+    readonly read: {
+        readonly get: true;
+        readonly getMany: true;
+        readonly maxGetManyKeys: {
+            readonly default: 100;
+            readonly maximum: 1000;
+        };
+        readonly maxParallelReads: {
+            readonly default: 8;
+            readonly maximum: 1000;
+        };
+    };
+    readonly query: {
+        readonly projection: {
+            readonly status: "unsupported";
+            readonly detail: "core StructuredQuery has no projection; every record is selected with select=* and no field is silently dropped";
+        };
+        readonly filter: {
+            readonly status: "native";
+            readonly detail: "simple column identifiers or DOCUMENT_ID; null only for equality and inequality; PostgREST control names select/columns/on_conflict/order/limit/offset/and/or are quoted as field keys so the predicate is preserved";
+        };
+        readonly sort: {
+            readonly status: "native";
+            readonly detail: "ascending or descending on simple column identifiers; queryWithSignal adds the configured primary key as a deterministic tie-breaker";
+        };
+        readonly pagination: {
+            readonly status: "native";
+            readonly detail: "limit/offset in query and queryWithSignal, plus an adapter-bound opaque keyset cursor for every non-empty page in queryWithSignal; a short page is not end-of-data; legacy query refuses cursors; no count=exact or full scan";
+        };
+        readonly joins: {
+            readonly status: "unsupported";
+        };
+        readonly aggregation: {
+            readonly status: "unsupported";
+        };
+        readonly grouping: {
+            readonly status: "unsupported";
+        };
+        readonly subquery: {
+            readonly status: "unsupported";
+        };
+        readonly fulltext: {
+            readonly status: "unsupported";
+        };
+        readonly timeseries: {
+            readonly status: "unsupported";
+        };
+        readonly native: {
+            readonly status: "unsupported";
+            readonly detail: "the adapter does not expose raw PostgREST query parameters, embedding, RPC or administration endpoints";
+        };
+        readonly discovery: {
+            readonly status: "native";
+            readonly detail: "read-only bounded OpenAPI discovery of relations, declared field types and declared primary keys for the request role; denied/disabled/empty metadata is explicit";
+        };
+    };
+    readonly bounds: {
+        readonly maxQueryLimit: {
+            readonly default: 100;
+            readonly maximum: 1000;
+        };
+        readonly maxQueryOffset: {
+            readonly default: 100000;
+            readonly maximum: 10000000;
+        };
+        readonly maxQueryPages: {
+            readonly default: 10000;
+            readonly maximum: 1000000;
+        };
+        readonly maxRequestBytes: {
+            readonly default: 1048576;
+            readonly maximum: 16777216;
+        };
+        readonly maxResponseBytes: {
+            readonly default: 1048576;
+            readonly maximum: 16777216;
+        };
+        readonly maxDiscoveryRelations: {
+            readonly default: 100;
+            readonly maximum: 10000;
+        };
+        readonly maxDiscoveryFieldsPerRelation: {
+            readonly default: 200;
+            readonly maximum: 10000;
+        };
+        readonly maxDiscoveryBytes: {
+            readonly default: 524288;
+            readonly maximum: 16777216;
+        };
+        readonly maxCursorBytes: {
+            readonly default: 8192;
+            readonly maximum: 65536;
+        };
+        readonly maxSchemaDepth: {
+            readonly default: 4;
+            readonly maximum: 16;
+        };
+        readonly filterOperators: readonly ["==", "!=", "<", "<=", ">", ">=", "in", "not-in", "array-contains", "array-contains-any"];
+        readonly orderDirections: readonly ["asc", "desc"];
+    };
+};
+export type PostgrestReadCapabilities = typeof POSTGREST_READ_CAPABILITIES;

package/dist/capabilities.js

@@ -0,0 +1,78 @@
+/**
+ * Honest read/query capabilities of the PostgREST adapter.
+ *
+ * It reads existing exposed relations and never rewrites rows into a DALgo
+ * envelope. Discovery is a bounded read of the OpenAPI document generated for
+ * the request role; it is not an administration API and not a promise that the
+ * role can read every advertised relation. Core `StructuredQuery` has no
+ * projection field, so projection is explicitly unsupported rather than
+ * silently ignored.
+ */
+export const POSTGREST_READ_CAPABILITIES = {
+    adapter: "@dalgo/dalgo2postgrest",
+    storage: "native-rows",
+    read: {
+        get: true,
+        getMany: true,
+        maxGetManyKeys: { default: 100, maximum: 1_000 },
+        maxParallelReads: { default: 8, maximum: 1_000 },
+    },
+    query: {
+        projection: {
+            status: "unsupported",
+            detail: "core StructuredQuery has no projection; every record is selected with select=* and no field is silently dropped",
+        },
+        filter: {
+            status: "native",
+            detail: "simple column identifiers or DOCUMENT_ID; null only for equality and inequality; PostgREST control names select/columns/on_conflict/order/limit/offset/and/or are quoted as field keys so the predicate is preserved",
+        },
+        sort: {
+            status: "native",
+            detail: "ascending or descending on simple column identifiers; queryWithSignal adds the configured primary key as a deterministic tie-breaker",
+        },
+        pagination: {
+            status: "native",
+            detail: "limit/offset in query and queryWithSignal, plus an adapter-bound opaque keyset cursor for every non-empty page in queryWithSignal; a short page is not end-of-data; legacy query refuses cursors; no count=exact or full scan",
+        },
+        joins: { status: "unsupported" },
+        aggregation: { status: "unsupported" },
+        grouping: { status: "unsupported" },
+        subquery: { status: "unsupported" },
+        fulltext: { status: "unsupported" },
+        timeseries: { status: "unsupported" },
+        native: {
+            status: "unsupported",
+            detail: "the adapter does not expose raw PostgREST query parameters, embedding, RPC or administration endpoints",
+        },
+        discovery: {
+            status: "native",
+            detail: "read-only bounded OpenAPI discovery of relations, declared field types and declared primary keys for the request role; denied/disabled/empty metadata is explicit",
+        },
+    },
+    bounds: {
+        maxQueryLimit: { default: 100, maximum: 1_000 },
+        maxQueryOffset: { default: 100_000, maximum: 10_000_000 },
+        maxQueryPages: { default: 10_000, maximum: 1_000_000 },
+        maxRequestBytes: { default: 1_048_576, maximum: 16_777_216 },
+        maxResponseBytes: { default: 1_048_576, maximum: 16_777_216 },
+        maxDiscoveryRelations: { default: 100, maximum: 10_000 },
+        maxDiscoveryFieldsPerRelation: { default: 200, maximum: 10_000 },
+        maxDiscoveryBytes: { default: 524_288, maximum: 16_777_216 },
+        maxCursorBytes: { default: 8_192, maximum: 65_536 },
+        maxSchemaDepth: { default: 4, maximum: 16 },
+        filterOperators: [
+            "==",
+            "!=",
+            "<",
+            "<=",
+            ">",
+            ">=",
+            "in",
+            "not-in",
+            "array-contains",
+            "array-contains-any",
+        ],
+        orderDirections: ["asc", "desc"],
+    },
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,OAAO,EAAE,wBAAwB;IACjC,OAAO,EAAE,aAAa;IACtB,IAAI,EAAE;QACJ,GAAG,EAAE,IAAI;QACT,OAAO,EAAE,IAAI;QACb,cAAc,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE;QAChD,gBAAgB,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE;KACjD;IACD,KAAK,EAAE;QACL,UAAU,EAAE;YACV,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,iHAAiH;SAC1H;QACD,MAAM,EAAE;YACN,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,sNAAsN;SAC/N;QACD,IAAI,EAAE;YACJ,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,sIAAsI;SAC/I;QACD,UAAU,EAAE;YACV,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,+NAA+N;SACxO;QACD,KAAK,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;QAChC,WAAW,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;QACtC,QAAQ,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;QACnC,QAAQ,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;QACnC,QAAQ,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;QACnC,UAAU,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;QACrC,MAAM,EAAE;YACN,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,wGAAwG;SACjH;QACD,SAAS,EAAE;YACT,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,mKAAmK;SAC5K;KACF;IACD,MAAM,EAAE;QACN,aAAa,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE;QAC/C,cAAc,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE;QACzD,aAAa,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE;QACtD,eAAe,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE;QAC5D,gBAAgB,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE;QAC7D,qBAAqB,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE;QACxD,6BAA6B,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE;QAChE,iBAAiB,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE;QAC5D,cAAc,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE;QACnD,cAAc,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;QAC3C,eAAe,EAAE;YACf,IAAI;YACJ,IAAI;YACJ,GAAG;YACH,IAAI;YACJ,GAAG;YACH,IAAI;YACJ,IAAI;YACJ,QAAQ;YACR,gBAAgB;YAChB,oBAAoB;SACrB;QACD,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;KACjC;CAC+C,CAAC"}