was-teaching-server 0.9.1

package/dist/backends/postgres.d.ts

@@ -0,0 +1,833 @@
+/**
+ * PostgreSQL persistence backend: stores Spaces, Collections, and Resources as
+ * rows (schema in postgresSchema.ts), and WebKMS keystores in a sibling table
+ * tree, implementing the same StorageBackend contract as the filesystem
+ * backend (types.ts). Selected by configuration (`DATABASE_URL`) and injected
+ * the same way (`createApp({ backend })`).
+ *
+ * Design departures from the filesystem backend (deliberate):
+ * - Quota accounting is transactional (`spaces.usage_bytes`, maintained in the
+ *   same transaction as every write/delete), making the per-Space capacity a
+ *   HARD limit under concurrency. "Usage" is exactly the stored content bytes;
+ *   descriptions, policies, and metadata are not counted (a divergence from
+ *   the filesystem's `du`, which counts every file).
+ * - Conditional writes use row locks (`SELECT ... FOR UPDATE`) and
+ *   transactions instead of the single-process `KeyedMutex`, so two server
+ *   processes sharing one database get correct conditional writes.
+ * - Blobs are buffered single-`bytea` writes bounded by `maxUploadBytes`; an
+ *   unset cap defaults to `DEFAULT_MAX_UPLOAD_BYTES` rather than "unbounded"
+ *   (unbounded buffering into a `bytea` is a footgun). Chunked-row streaming
+ *   is a planned follow-up increment.
+ * - `exportSpace` / `importSpace` speak the same tar dialect as the
+ *   filesystem backend (same file-name codecs, same manifest), so archives
+ *   migrate between the two backends in either direction; the Postgres import
+ *   apply loop additionally runs in a single transaction (atomic rollback).
+ */
+import { Readable } from 'node:stream';
+import type { FastifyBaseLogger } from 'fastify';
+import type { BlindedIndexQuery, BlindedIndexQueryPage } from '../lib/blindedIndex.js';
+import type { SpaceDescription, CollectionDescription, CollectionSummary, CollectionResourcesList, ResourceResult, ResourceMetadata, ResourceMetadataCustom, ResourceInput, ImportStats, PolicyDocument, BackendDescriptor, BackendUsage, StorageBackend, StoredBackendRecord, KeystoreConfig, KmsKeyRecord, RevocationRecord, RevocationScope, CapabilitySummary, IDID } from '../types.js';
+export declare class PostgresBackend implements StorageBackend {
+    logger: FastifyBaseLogger;
+    /**
+     * Per-Space storage capacity, in bytes (spec "Quotas"). `undefined` means no
+     * configured limit. Unlike the filesystem backend's `du`-sampled soft limit,
+     * this is enforced transactionally on every content write -- a HARD limit
+     * under concurrency.
+     */
+    capacityBytes?: number;
+    /**
+     * Largest single upload accepted, in bytes (spec "Quotas",
+     * `maxUploadBytes`). Always set on this backend: an unconfigured cap
+     * defaults to `DEFAULT_MAX_UPLOAD_BYTES`, because every blob write buffers
+     * through memory on the single-`bytea` path.
+     */
+    maxUploadBytes: number;
+    /**
+     * Max Spaces a single controller may create (spec "Quotas", a default-on
+     * count quota). `undefined` means no cap. Enforced transactionally on the
+     * Space create path (`writeSpace`), serialized per controller by an advisory
+     * lock -- a HARD limit under concurrency, like the byte quota. The
+     * constructor normalizes an unset option to
+     * {@link DEFAULT_MAX_SPACES_PER_CONTROLLER} and a non-finite option
+     * (`Infinity`) to `undefined`.
+     */
+    maxSpacesPerController?: number;
+    /**
+     * Max Collections a single Space may hold (spec "Quotas", a default-on count
+     * quota). `undefined` means no cap. Enforced on the Collection create path,
+     * serialized per Space by the space row lock. Normalized like
+     * {@link maxSpacesPerController}.
+     */
+    maxCollectionsPerSpace?: number;
+    /**
+     * Max live Resources a single Space may hold across all its Collections (spec
+     * "Quotas", a default-on count quota). `undefined` means no cap. Enforced on
+     * the Resource create path (a tombstone does not count). Normalized like
+     * {@link maxSpacesPerController}.
+     */
+    maxResourcesPerSpace?: number;
+    private _pool;
+    private _schema?;
+    /**
+     * @param options {object}
+     * @param options.connectionString {string}   a `postgres://` URL
+     * @param [options.schema] {string}   Postgres schema to operate in (set as
+     *   the connection `search_path`; created by `init()` if absent). Used for
+     *   test isolation; production uses the default `public`.
+     * @param [options.logger] {FastifyBaseLogger}
+     * @param [options.capacityBytes] {number}   per-Space quota in bytes; a
+     *   finite value is enforced, `undefined` or a non-finite value means no
+     *   configured limit
+     * @param [options.maxUploadBytes] {number}   per-upload cap in bytes;
+     *   `undefined` applies the `DEFAULT_MAX_UPLOAD_BYTES` default. A non-finite
+     *   value (`Infinity`, from `MAX_UPLOAD_BYTES=unlimited`) throws: this backend
+     *   buffers each upload in memory as a single `bytea`, so an unbounded cap is
+     *   not supported.
+     * @param [options.maxSpacesPerController] {number}   max Spaces per
+     *   controller (spec "Quotas"); `undefined` applies the default-on limit,
+     *   `Infinity` means no cap
+     * @param [options.maxCollectionsPerSpace] {number}   max Collections per
+     *   Space; `undefined` applies the default-on limit, `Infinity` means no cap
+     * @param [options.maxResourcesPerSpace] {number}   max live Resources per
+     *   Space; `undefined` applies the default-on limit, `Infinity` means no cap
+     */
+    constructor({ connectionString, schema, logger, capacityBytes, maxUploadBytes, maxSpacesPerController, maxCollectionsPerSpace, maxResourcesPerSpace }: {
+        connectionString: string;
+        schema?: string;
+        logger?: FastifyBaseLogger;
+        capacityBytes?: number;
+        maxUploadBytes?: number;
+        maxSpacesPerController?: number;
+        maxCollectionsPerSpace?: number;
+        maxResourcesPerSpace?: number;
+    });
+    /**
+     * Connects and applies schema migrations (idempotent, advisory-locked; see
+     * postgresSchema.ts). Called once by the `createApp` composition before the
+     * server starts listening.
+     * @returns {Promise<void>}
+     */
+    init(): Promise<void>;
+    /**
+     * Drains the connection pool. Wired to the Fastify `onClose` hook by the
+     * plugin composition.
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+    /**
+     * Runs `fn` inside one transaction on a dedicated client, committing on
+     * success and rolling back on any throw.
+     * @param fn {(client: pg.PoolClient) => Promise<T>}
+     * @returns {Promise<T>}
+     */
+    private _withTransaction;
+    /**
+     * Self-description advertised at `GET /space/:spaceId/backends`. Same
+     * affordances as the filesystem backend: conditional writes (ETag
+     * validators, row-locked preconditions) and the `changes` and
+     * `blinded-index` query profiles.
+     * @returns {Required<Omit<BackendDescriptor, 'provider' | 'connection'>>}
+     */
+    describe(): Required<Omit<BackendDescriptor, 'provider' | 'connection'>>;
+    /**
+     * Ensures the `spaces` row for `spaceId` exists (a placeholder with a NULL
+     * description when the Space was never described -- the analogue of the
+     * filesystem creating a Space directory on a sub-Space write).
+     * @param options {object}
+     * @param options.client {pg.PoolClient}
+     * @param options.spaceId {string}
+     * @returns {Promise<void>}
+     */
+    private _ensureSpaceRow;
+    /**
+     * Ensures the `collections` row (and its parent `spaces` row) exists,
+     * placeholder-description like `_ensureSpaceRow`.
+     * @param options {object}
+     * @param options.client {pg.PoolClient}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {Promise<void>}
+     */
+    private _ensureCollectionRow;
+    /**
+     * Applies a usage delta to the Space's transactional quota counter,
+     * enforcing the configured capacity in the same statement (the hard-limit
+     * departure from the filesystem's `du`-sampled soft check). Zero rows
+     * updated with the row present means the write would not fit:
+     * `QuotaExceededError` (507), rolling back the enclosing transaction.
+     * MUST run inside the same transaction as the content mutation.
+     * @param options {object}
+     * @param options.client {pg.PoolClient}
+     * @param options.spaceId {string}
+     * @param options.delta {number}   signed byte delta (new minus old size)
+     * @returns {Promise<void>}
+     */
+    private _applyUsageDelta;
+    /**
+     * Reports the Space's usage from the transactional counter (no measurement
+     * pass, no cache). The per-Collection breakdown is computed on demand with
+     * one aggregate query.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.includeCollections] {boolean}
+     * @returns {Promise<BackendUsage>}
+     */
+    reportUsage({ spaceId, includeCollections }: {
+        spaceId: string;
+        includeCollections?: boolean;
+    }): Promise<BackendUsage>;
+    /**
+     * Reports a single Collection's usage (its `SUM(size_bytes)` slice), with
+     * `state` / `limit` derived from the Space total (the quota is a per-Space
+     * limit).
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {Promise<BackendUsage>}
+     */
+    reportCollectionUsage({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): Promise<BackendUsage>;
+    /**
+     * Builds the shared quota-report condition fields (see
+     * `lib/backendUsage.ts`).
+     * @param options {object}
+     * @param options.usageBytes {number}
+     * @param options.spaceTotalBytes {number}
+     * @returns {Omit<BackendUsage, 'measuredAt' | 'usageByCollection'>}
+     */
+    private _backendUsageFields;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.spaceDescription {SpaceDescription}
+     * @param [options.createdBy] {string}   DID of the invoker, recorded as the
+     *   Space's `createdBy` on first write only
+     * @returns {Promise<void>}
+     */
+    writeSpace({ spaceId, spaceDescription, createdBy }: {
+        spaceId: string;
+        spaceDescription: SpaceDescription;
+        createdBy?: IDID;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<SpaceDescription|undefined>}   falsy when the Space does
+     *   not exist or is a placeholder row without a description
+     */
+    getSpaceDescription({ spaceId }: {
+        spaceId: string;
+    }): Promise<SpaceDescription | undefined>;
+    /**
+     * Deletes the Space row; collections, resources, policies, and backend
+     * records go with it via `ON DELETE CASCADE` (keystores are a sibling tree
+     * and are deliberately untouched). Idempotent.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<void>}
+     */
+    deleteSpace({ spaceId }: {
+        spaceId: string;
+    }): Promise<void>;
+    /**
+     * Every described Space, sorted by id (byte order via `COLLATE "C"`).
+     * Placeholder rows without a description are skipped, like a Space dir
+     * without a readable description file.
+     * @returns {Promise<SpaceDescription[]>}
+     */
+    listSpaces(): Promise<SpaceDescription[]>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.collectionDescription {CollectionDescription}
+     * @param [options.createdBy] {string}   DID of the invoker, recorded as the
+     *   Collection's `createdBy` on first write only
+     * @param [options.ifMatch] {string}   an `If-Match` compare-and-swap on the
+     *   current description version (the `key-epochs` feature); a stale validator
+     *   throws `PreconditionFailedError` (412)
+     * @returns {Promise<{ version: number }>}   the Collection's new description
+     *   version (the `ETag` validator)
+     */
+    writeCollection({ spaceId, collectionId, collectionDescription, createdBy, ifMatch, assertTransition }: {
+        spaceId: string;
+        collectionId: string;
+        collectionDescription: CollectionDescription;
+        createdBy?: IDID;
+        ifMatch?: string;
+        assertTransition?: (prior?: CollectionDescription & {
+            descriptionVersion?: number;
+        }) => void;
+    }): Promise<{
+        version: number;
+    }>;
+    /**
+     * The one Collection-description upsert statement, shared by
+     * `writeCollection` and the import apply loop. `createdBy` is resolved
+     * within this same statement, in one round trip (no separate read-then-write
+     * race with a concurrent write for the same id):
+     * - `collections.description IS NULL` means there is no prior description
+     *   row (a placeholder row created by a sub-Resource write before any
+     *   Collection Description was written) -- this write IS the create, so it
+     *   behaves like the insert branch: attach the `createdBy` parameter when
+     *   present, otherwise omit the key entirely (never store it as JSON
+     *   `null`).
+     * - Otherwise a prior description exists, and its `createdBy` -- present or
+     *   absent -- is preserved verbatim via the jsonb `?` key-existence
+     *   operator; the `createdBy` parameter is ignored entirely (never
+     *   backfilled).
+     * Any `createdBy` embedded in `collectionDescription` itself is discarded
+     * here: `writeCollection` passes the invoker DID via the `createdBy`
+     * parameter instead, and the import apply loop passes the imported
+     * document's own `createdBy` so a restored Collection keeps its original
+     * creator (that import call is always a create -- the caller skips existing
+     * Collections -- so there is no prior row to preserve instead).
+     * @param options {object}
+     * @param options.queryable {Queryable}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.collectionDescription {CollectionDescription}
+     * @param [options.createdBy] {string}   resolved creator to fall back to
+     *   when there is no prior row
+     * @param [options.descriptionVersion] {number}   the monotonic description
+     *   version to stamp (the `ETag` validator; the `key-epochs` feature), kept
+     *   OUT of the `description` jsonb -- it lives in the `description_version`
+     *   column and travels only as the `ETag` header. When omitted (the import
+     *   path), a `_version` on the incoming archived description is used, else 1.
+     * @returns {Promise<void>}
+     */
+    private _upsertCollection;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {Promise<(CollectionDescription & { descriptionVersion?: number })
+     *   | undefined>}   `descriptionVersion` is the out-of-band `ETag` validator.
+     */
+    getCollectionDescription({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): Promise<(CollectionDescription & {
+        descriptionVersion?: number;
+    }) | undefined>;
+    /**
+     * Deletes the Collection row (resources cascade), its policies, and
+     * subtracts the Collection's stored bytes from the Space usage counter --
+     * all in one transaction. Idempotent.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @returns {Promise<void>}
+     */
+    deleteCollection({ spaceId, collectionId }: {
+        spaceId: string;
+        collectionId: string;
+    }): Promise<void>;
+    /**
+     * Every Collection row in the Space, sorted by id. A row without a
+     * description (created by a sub-Collection write) falls back to the id for
+     * its `name`, like a description-less directory on the filesystem.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<CollectionSummary[]>}
+     */
+    listCollections({ spaceId }: {
+        spaceId: string;
+    }): Promise<CollectionSummary[]>;
+    /**
+     * Lists a Collection's Resources, cursor-paginated with the same keyset
+     * (ascending `resourceId`, byte order), cursor codec, clamps, and `next`
+     * construction as the filesystem backend. Tombstones are invisible.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param [options.limit] {number}
+     * @param [options.cursor] {string}
+     * @param [options.collectionDescription] {CollectionDescription}
+     * @returns {Promise<CollectionResourcesList>}
+     */
+    listCollectionItems({ spaceId, collectionId, limit, cursor, collectionDescription: providedDescription }: {
+        spaceId: string;
+        collectionId: string;
+        limit?: number;
+        cursor?: string;
+        collectionDescription?: CollectionDescription;
+    }): Promise<CollectionResourcesList>;
+    /**
+     * Writes a Resource representation as one transaction: row lock, shared
+     * precondition evaluation (exact filesystem semantics -- a tombstone counts
+     * as "not exists", `ifNoneMatch` precedence per RFC9110), monotonic
+     * `version` bump continuing through delete/recreate, and the transactional
+     * quota delta. JSON is stored as its serialized UTF-8 bytes; blobs buffer
+     * through the capped accumulator.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.input {ResourceInput}
+     * @param [options.createdBy] {string}   DID of the invoker, recorded as the
+     *   Resource's `createdBy` on first write only
+     * @param [options.ifMatch] {string}
+     * @param [options.ifNoneMatch] {boolean}
+     * @returns {Promise<{ version: number }>}
+     */
+    writeResource({ spaceId, collectionId, resourceId, input, createdBy, epoch, ifMatch, ifNoneMatch }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+        input: ResourceInput;
+        createdBy?: IDID;
+        epoch?: string;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+    }): Promise<{
+        version: number;
+    }>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param [options.contentType] {string}   advisory; ignored for lookup
+     * @returns {Promise<ResourceResult>}
+     */
+    getResource({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+        contentType?: string;
+    }): Promise<ResourceResult>;
+    /**
+     * Soft-deletes a Resource into a tombstone row: content dropped, `deleted`
+     * set, `version` bumped (so the change feed surfaces it), last-known
+     * `content_type` retained, `custom` / `meta_version` dropped, and the freed
+     * bytes subtracted from the quota counter -- one transaction. Idempotent on
+     * an absent Resource or an existing tombstone.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param [options.ifMatch] {string}
+     * @returns {Promise<void>}
+     */
+    deleteResource({ spaceId, collectionId, resourceId, ifMatch }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+        ifMatch?: string;
+    }): Promise<void>;
+    /**
+     * Reads the metadata of a Resource's current representation. Tombstones and
+     * absent Resources resolve `undefined`. `custom` is included only when
+     * non-empty, verbatim (`{ name, tags }` or the opaque envelope).
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @returns {Promise<(ResourceMetadata & { createdBy?: IDID; version?:
+     *   number; metaVersion?: number }) | undefined>}
+     */
+    getResourceMetadata({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+    }): Promise<(ResourceMetadata & {
+        createdBy?: IDID;
+        version?: number;
+        metaVersion?: number;
+    }) | undefined>;
+    /**
+     * Replaces the user-writable `custom` object (full replacement; `{}`
+     * clears), bumping `updatedAt` and the independent `metaVersion` -- one
+     * row-locked transaction, preconditions evaluated on the current
+     * `metaVersion` via the shared helper. Resolves `undefined` (no create) for
+     * an absent or tombstoned Resource.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.custom {ResourceMetadataCustom | Record<string, unknown>}
+     * @param [options.ifMatch] {string}
+     * @param [options.ifNoneMatch] {boolean}
+     * @returns {Promise<{ metaVersion: number } | undefined>}
+     */
+    writeResourceMetadata({ spaceId, collectionId, resourceId, custom, epoch, ifMatch, ifNoneMatch }: {
+        spaceId: string;
+        collectionId: string;
+        resourceId: string;
+        custom: ResourceMetadataCustom | Record<string, unknown>;
+        epoch?: string;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+    }): Promise<{
+        metaVersion: number;
+    } | undefined>;
+    /**
+     * Replication change feed (the `changes` query profile): one indexed keyset
+     * query over `(updatedAt, resourceId)`, tombstones included, JSON documents
+     * only, bodies parsed for the returned page.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param [options.checkpoint] {{ id: string, updatedAt: string }}
+     * @param options.limit {number}
+     * @returns {Promise<{ documents: Array<object>, checkpoint: object | null }>}
+     */
+    changesSince({ spaceId, collectionId, checkpoint, limit }: {
+        spaceId: string;
+        collectionId: string;
+        checkpoint?: {
+            id: string;
+            updatedAt: string;
+        };
+        limit: number;
+    }): Promise<{
+        documents: Array<{
+            resourceId: string;
+            version: number;
+            metaVersion?: number;
+            createdBy?: IDID;
+            updatedAt: string;
+            deleted: boolean;
+            data?: unknown;
+            custom?: ResourceMetadataCustom | Record<string, unknown>;
+            epoch?: string;
+        }>;
+        checkpoint: {
+            id: string;
+            updatedAt: string;
+        } | null;
+    }>;
+    /**
+     * Blinded-index query (the `blinded-index` query profile; see the
+     * `StorageBackend.queryByBlindedIndex` contract). Selects the Collection's
+     * live JSON rows, parses each body, and hands the candidates to the shared
+     * evaluator (`lib/blindedIndex.ts`) for matching, ordering, and cursor
+     * pagination -- identical semantics to the filesystem backend. A full scan
+     * of the Collection per call, deliberate for this teaching backend; an
+     * indexed variant would flatten the blinded attributes into an indexed
+     * token side-table (the bedrock-edv-storage strategy). Unparsable JSON is
+     * skipped.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.query {BlindedIndexQuery}
+     * @param [options.count] {boolean}   return only the match count
+     * @param [options.limit] {number}   requested page size
+     * @param [options.cursor] {string}   opaque cursor from a prior page
+     * @returns {Promise<{ count: number } | BlindedIndexQueryPage>}
+     */
+    queryByBlindedIndex({ spaceId, collectionId, query, count, limit, cursor }: {
+        spaceId: string;
+        collectionId: string;
+        query: BlindedIndexQuery;
+        count?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        count: number;
+    } | BlindedIndexQueryPage>;
+    /**
+     * Maps the optional-id policy addressing onto the sentinel-column primary
+     * key: Space policy `('', '')`, Collection policy `(cid, '')`, Resource
+     * policy `(cid, rid)`.
+     * @param options {object}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @returns {{ collectionKey: string, resourceKey: string }}
+     */
+    private _policyKey;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @returns {Promise<PolicyDocument|undefined>}
+     */
+    getPolicy({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId?: string;
+        resourceId?: string;
+    }): Promise<PolicyDocument | undefined>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @param options.policy {PolicyDocument}
+     * @returns {Promise<void>}
+     */
+    writePolicy({ spaceId, collectionId, resourceId, policy }: {
+        spaceId: string;
+        collectionId?: string;
+        resourceId?: string;
+        policy: PolicyDocument;
+    }): Promise<void>;
+    /**
+     * The one policy upsert statement, shared by `writePolicy` and the import
+     * apply loop; keys through `_policyKey` so the sentinel convention lives in
+     * one place.
+     * @param options {object}
+     * @param options.queryable {Queryable}
+     * @param options.spaceId {string}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @param options.policy {PolicyDocument}
+     * @returns {Promise<void>}
+     */
+    private _upsertPolicy;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param [options.collectionId] {string}
+     * @param [options.resourceId] {string}
+     * @returns {Promise<void>}   idempotent
+     */
+    deletePolicy({ spaceId, collectionId, resourceId }: {
+        spaceId: string;
+        collectionId?: string;
+        resourceId?: string;
+    }): Promise<void>;
+    /**
+     * Persists a full (secret-bearing) backend-registration record. Upsert.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.backendId {string}
+     * @param options.record {StoredBackendRecord}
+     * @returns {Promise<void>}
+     */
+    writeBackend({ spaceId, backendId, record }: {
+        spaceId: string;
+        backendId: string;
+        record: StoredBackendRecord;
+    }): Promise<void>;
+    /**
+     * The full (secret-bearing) record, or `undefined`. The only method that
+     * exposes secret connection material -- internal use.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.backendId {string}
+     * @returns {Promise<StoredBackendRecord|undefined>}
+     */
+    getBackend({ spaceId, backendId }: {
+        spaceId: string;
+        backendId: string;
+    }): Promise<StoredBackendRecord | undefined>;
+    /**
+     * The Space's registered backends, **sanitized** (mapped through
+     * `sanitizeBackendRecord` -- the secret boundary is unchanged), sorted by id.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<BackendDescriptor[]>}
+     */
+    listBackends({ spaceId }: {
+        spaceId: string;
+    }): Promise<BackendDescriptor[]>;
+    /**
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.backendId {string}
+     * @returns {Promise<void>}   idempotent
+     */
+    deleteBackend({ spaceId, backendId }: {
+        spaceId: string;
+        backendId: string;
+    }): Promise<void>;
+    /**
+     * Persists a keystore config unconditionally (the create path; local ids
+     * are server-generated random values). The queryable/gated fields
+     * (`controller`, `sequence`, `kmsModule`) are denormalized alongside the
+     * verbatim config.
+     * @param options {object}
+     * @param options.keystoreId {string}
+     * @param options.config {KeystoreConfig}
+     * @returns {Promise<void>}
+     */
+    writeKeystore({ keystoreId, config }: {
+        keystoreId: string;
+        config: KeystoreConfig;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.keystoreId {string}
+     * @returns {Promise<KeystoreConfig|undefined>}
+     */
+    getKeystore({ keystoreId }: {
+        keystoreId: string;
+    }): Promise<KeystoreConfig | undefined>;
+    /**
+     * Replaces a keystore config, gated atomically in one conditional `UPDATE`:
+     * the row must exist with `sequence` exactly one less than the incoming
+     * config's and an unchanged `kmsModule`. Zero rows updated -- missing
+     * keystore, stale sequence, or module change alike -- rejects with the
+     * protocol's single merged 409 (`KeystoreStateConflictError`).
+     * @param options {object}
+     * @param options.keystoreId {string}
+     * @param options.config {KeystoreConfig}
+     * @returns {Promise<void>}
+     */
+    updateKeystore({ keystoreId, config }: {
+        keystoreId: string;
+        config: KeystoreConfig;
+    }): Promise<void>;
+    /**
+     * Every stored keystore config whose `controller` matches, sorted by local
+     * id (the request layer caps the wire result).
+     * @param options {object}
+     * @param options.controller {IDID}
+     * @returns {Promise<KeystoreConfig[]>}
+     */
+    listKeystoresByController({ controller }: {
+        controller: IDID;
+    }): Promise<KeystoreConfig[]>;
+    /**
+     * Inserts a key record, create-only: the primary key enforces the
+     * `(keystoreId, localId)` uniqueness atomically; a duplicate rejects with
+     * the protocol's 409 (`KeyIdConflictError`). The record is stored verbatim
+     * (opaque to storage -- the at-rest cipher applies above the backend).
+     * @param options {object}
+     * @param options.keystoreId {string}
+     * @param options.localId {string}
+     * @param options.record {KmsKeyRecord}
+     * @returns {Promise<void>}
+     */
+    insertKey({ keystoreId, localId, record }: {
+        keystoreId: string;
+        localId: string;
+        record: KmsKeyRecord;
+    }): Promise<void>;
+    /**
+     * @param options {object}
+     * @param options.keystoreId {string}
+     * @param options.localId {string}
+     * @returns {Promise<KmsKeyRecord|undefined>}
+     */
+    getKey({ keystoreId, localId }: {
+        keystoreId: string;
+        localId: string;
+    }): Promise<KmsKeyRecord | undefined>;
+    /**
+     * Every stored key record under the keystore, sorted by local id (the request
+     * layer caps and paginates the wire result). An empty keystore resolves an
+     * empty list. The record is returned verbatim -- the at-rest cipher applies
+     * above the backend.
+     * @param options {object}
+     * @param options.keystoreId {string}
+     * @returns {Promise<Array<{ localId: string, record: KmsKeyRecord }>>}
+     */
+    listKeys({ keystoreId }: {
+        keystoreId: string;
+    }): Promise<Array<{
+        localId: string;
+        record: KmsKeyRecord;
+    }>>;
+    /**
+     * Resolves a revocation scope to the table it lives in, the scope column
+     * within that table, and the scope id value. The returned `table` and
+     * `column` are server-chosen constants (never user input), so callers may
+     * safely interpolate them into a SQL template; `id` remains a bound value.
+     * @param scope {RevocationScope}
+     * @returns {{ table: string, column: string, id: string }}
+     */
+    private _revocationTable;
+    /**
+     * Inserts a revocation record, create-only on
+     * `(scope id, delegator, capability.id)`; a duplicate rejects with the
+     * protocol's 409 (`DuplicateRevocationError`).
+     * @param options {object}
+     * @param options.scope {RevocationScope}
+     * @param options.record {RevocationRecord}
+     * @returns {Promise<void>}
+     */
+    insertRevocation({ scope, record }: {
+        scope: RevocationScope;
+        record: RevocationRecord;
+    }): Promise<void>;
+    /**
+     * True when any of the given capabilities has a stored, unexpired
+     * revocation under the scope. A single read-only SELECT: rows past their
+     * `meta.expires` GC horizon are filtered out in the predicate rather than
+     * pruned here -- this runs on every delegated-chain verification, so it
+     * must not write; `insertRevocation` prunes on the (rare) write path
+     * instead. ISO-8601 strings compare correctly under the column's byte-order
+     * collation.
+     * @param options {object}
+     * @param options.scope {RevocationScope}
+     * @param options.capabilities {CapabilitySummary[]}
+     * @returns {Promise<boolean>}
+     */
+    isRevoked({ scope, capabilities }: {
+        scope: RevocationScope;
+        capabilities: CapabilitySummary[];
+    }): Promise<boolean>;
+    /**
+     * Builds the filesystem-dialect sidecar object for a resource row (the
+     * `.meta.<id>.json` shape), field order matching the filesystem writer so
+     * archives stay as close to byte-compatible as jsonb round-tripping allows.
+     * @param row {Omit<ResourceRow, 'content'>}
+     * @returns {SidecarShape}
+     */
+    private _sidecarFor;
+    /**
+     * Exports the Space as a tar stream in the exact filesystem on-disk layout
+     * (same file-name codecs, same manifest), so the archive imports into
+     * either backend. Backend registration records are excluded (secret
+     * material), exactly as on the filesystem.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @returns {Promise<Readable>}   tar-stream pack
+     */
+    exportSpace({ spaceId }: {
+        spaceId: string;
+    }): Promise<Readable>;
+    /**
+     * Fetches one resource's content bytes for the export pack loop. A row
+     * deleted or tombstoned between the metadata pass and this read (the export
+     * is not one transaction, same as the filesystem's racy directory walk)
+     * yields an empty body rather than failing the whole archive.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @returns {Promise<Buffer>}
+     */
+    private _resourceContent;
+    /**
+     * Merges a WAS space-export tarball into an existing Space with the same
+     * three-invariant pre-flight (per-entry 413, fail-closed 422 encryption
+     * conformance, cumulative 507) and skip-not-overwrite merge semantics as
+     * the filesystem backend -- including tombstone carry-over and "a tombstone
+     * blocks resurrection". One strict improvement: the entire apply loop runs
+     * in a single transaction, so a mid-import failure leaves the Space
+     * untouched atomically.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.tarStream {Readable}
+     * @returns {Promise<ImportStats>}
+     */
+    importSpace({ spaceId, tarStream }: {
+        spaceId: string;
+        tarStream: Readable;
+    }): Promise<ImportStats>;
+    /**
+     * Inserts one archived resource (or orphan tombstone) row for the import
+     * apply loop. Timestamps, versions, `createdBy`, and `custom` come from the
+     * archive's sidecar when present; an archive resource without a sidecar is
+     * treated as a fresh first write on this backend (version 1, no
+     * `createdBy`).
+     * @param options {object}
+     * @param options.client {pg.PoolClient}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.contentType {string}
+     * @param options.body {Buffer|null}   `null` re-creates a tombstone
+     * @param [options.sidecar] {SidecarShape}
+     * @returns {Promise<void>}
+     */
+    private _insertImportedResource;
+}
+//# sourceMappingURL=postgres.d.ts.map