@dudousxd/nestjs-catalog 0.10.0 → 0.12.0

package/dist/catalog.secrets.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Encrypting the credential that has to rest in `catalog_connection.config`.
+ *
+ * `config-secrets.ts` in the pipeline package closed the HTTP half of this: a
+ * connection URL is a password with an address attached, `config` is served by
+ * `GET pipeline/connections` under `catalog:read`, and the redaction stopped it
+ * travelling in a response. `MySqlPipelineStore` closed the write half: a
+ * password-bearing URL that is not already stored is refused, with a message
+ * naming `secretEnvVar`.
+ *
+ * Neither touches the thing this file is about. A redaction protects a reader
+ * coming through the API. It does nothing at all for a database dump, a read
+ * replica, a nightly backup, or anybody holding `SELECT` on the RDS instance —
+ * and for those, `config` is still a list of every password the catalog knows.
+ * `allowInlineCredentials` makes that population larger on purpose, which is
+ * precisely why encryption becomes worth building at the same time as the flag
+ * that needs it.
+ *
+ * ## A seam, not an implementation
+ *
+ * There is no cipher in this file and there must not be one. A library that
+ * shipped AES with a key read from an environment variable would have moved the
+ * problem from one column to one variable, and would have to answer for key
+ * rotation, per-environment separation, and an audit trail — all of which the
+ * host's KMS, Vault, or HSM already answers for, and none of which this package
+ * can answer for on its behalf. What is here is the shape of the question, so a
+ * provider can be written against it: {@link CatalogSecretVault}.
+ *
+ * The library never inspects a ciphertext, never chooses a key, and never
+ * decides an algorithm. It decides *which values* are secrets, *when* they are
+ * sealed, and *what happens when the vault cannot be reached* — three questions
+ * a provider should not have to have an opinion about.
+ *
+ * ## What the default does
+ *
+ * Refuses. {@link RefusingSecretVault} throws on `seal`, naming the token to
+ * bind. A default that quietly stored plaintext would be the worst shape
+ * available here: a host would turn `encryptCredentials` on, see saves succeed,
+ * and have exactly the same column contents as before with a docblock now
+ * claiming otherwise. Every other refusing default in this codebase exists for
+ * the same reason — `CATALOG_LOAD_EXPECTATIONS` unbound means incremental loads
+ * are refused rather than silently unpoliced.
+ */
+/**
+ * What a vault hands back. Stored verbatim; opaque to this library.
+ *
+ * Three fields and no fourth, because everything a rotation needs is here and
+ * nothing a reader could misuse is: the ciphertext says nothing without the
+ * vault, and the vault says nothing without the key. It is a plain JSON object
+ * so that it can sit in the same `json` column the plaintext sat in — no
+ * migration, no second table, and a column that may hold either form for as
+ * long as it takes a deployment to move over. {@link isSealedSecret} is what
+ * tells the two apart on the way out.
+ */
+export interface SealedSecret {
+    /** Which vault sealed it — `CatalogSecretVault.name`. */
+    vault: string;
+    /** Which key, in whatever form that vault names keys. */
+    keyId: string;
+    /**
+     * An opaque string the vault chose. **Not base64, and never decoded here.**
+     *
+     * This said "base64" first, and both provider implementations proved it
+     * wrong from opposite directions: HashiCorp Transit returns
+     * `vault:v1:<base64>`, which has two colons and is not decodable as base64 at
+     * all. The provider stores that verbatim and is right to — the `v1` is the
+     * row's only self-description of which key version sealed it, and
+     * `transit/rewrap` takes exactly that string back.
+     *
+     * The claim was harmless while nothing acted on it, which is what makes it
+     * worth correcting now rather than later: the day something takes it
+     * literally — a base64 `CHECK` constraint, a JSON-schema `contentEncoding`, a
+     * `Buffer.from(value, 'base64')` round trip — it breaks **silently**, because
+     * `Buffer.from` does not throw on input it cannot read. It returns different
+     * bytes.
+     *
+     * So the only rule is: non-empty, and given back to the vault exactly as it
+     * came. {@link isSealedSecret} checks that it is a non-empty string and must
+     * never be tightened past that — any narrower test encodes one vault's format
+     * as the contract and silently rejects the next one's rows.
+     */
+    ciphertext: string;
+}
+/**
+ * Where a secret is being used, so a vault can scope or audit by it.
+ *
+ * Passed to `open` as well as to `seal`, and that is the interesting half: a
+ * KMS provider can put this in an encryption context so a ciphertext sealed for
+ * `connection/abc/url` cannot be replayed as `connector/xyz/url`, and a Vault
+ * provider can write an audit line naming the row somebody's credential was
+ * read for. Neither is possible if the seam only carries bytes.
+ */
+export interface SecretContext {
+    /** `connection` or `connector`. */
+    kind: string;
+    /**
+     * The row's id. Present and stable whenever `MySqlPipelineStore` is the
+     * caller, including on a first save.
+     *
+     * This said "absent on a first save", and both provider implementations
+     * independently left `id` out of their encryption context because of it —
+     * correctly, given what it said. A context that is absent on create and
+     * present on update seals under one context and opens under another, and the
+     * failure lands at the first connector run rather than at the save.
+     *
+     * So the store was changed rather than the providers: it mints the row's id
+     * *before* sealing instead of inside `em.create`, which costs one hoisted
+     * `randomUUID()` and makes the binding property real. A provider may now put
+     * this in an encryption context and get what the seam always claimed —
+     * `connection/abc/url` is not replayable as `connection/xyz/url`.
+     *
+     * Two things this does NOT make true, both worth stating before somebody
+     * relies on them:
+     *
+     *  - It is still optional in the type, because a host calling a vault
+     *    directly is not obliged to have a row. A provider that binds it must
+     *    decide what an absent `id` means for its own callers.
+     *  - **Rows sealed before this existed were sealed without it.** A provider
+     *    that starts binding `id` on a deployment that already has sealed rows
+     *    strands every one of them. Binding it is safe on a new deployment, and
+     *    on an existing one only behind a re-seal.
+     */
+    id?: string;
+    /** The config key being sealed — `url`, `password`. */
+    field: string;
+}
+/**
+ * The seam a host binds to make credentials unreadable in the catalog's own
+ * database.
+ *
+ * Both methods are async and both are expected to fail sometimes: they are
+ * network calls to something outside this process. What each failure *means*
+ * is not symmetric, and the store treats them differently — see
+ * {@link SecretSealFailedError} and {@link SecretOpenFailedError}.
+ */
+export interface CatalogSecretVault {
+    /**
+     * Stable, stored on every SealedSecret so a rotation can find its own.
+     *
+     * Stable across deployments and releases, not merely across a process: it is
+     * written into rows. Renaming it strands every row already sealed under the
+     * old name, which the store refuses loudly rather than guessing at — a bound
+     * vault whose name does not match the row's is not asked to try.
+     */
+    readonly name: string;
+    seal(plaintext: string, context: SecretContext): Promise<SealedSecret>;
+    open(sealed: SealedSecret, context: SecretContext): Promise<string>;
+}
+/**
+ * The token a host binds one vault — or several — to.
+ *
+ * **Several is the supported shape, and it is what makes rotation possible.**
+ * Bind `CatalogSecretVault[]` and the store seals with the *first* and opens
+ * with whichever one's `name` matches the row. Moving from one vault to another
+ * is then: bind `[next, current]`, let saves reseal under `next`, and drop
+ * `current` when nothing is sealed under it any more. With a single vault that
+ * transition has no middle — the moment `next` is bound, every row sealed by
+ * `current` is unreadable — and a library that made rotation require an outage
+ * would be a library whose keys never got rotated.
+ *
+ * `@Optional()` where it is injected, so a host that binds nothing still boots.
+ * It then gets {@link RefusingSecretVault}, which costs nothing until something
+ * actually asks for a seal.
+ */
+export declare const CATALOG_SECRET_VAULT: unique symbol;
+/**
+ * Whether a value that came back out of a JSON column is a sealed secret.
+ *
+ * A runtime guard and not a cast, because this is a `json` column: MikroORM
+ * hands back whatever is in it, and what is in it may have been written by a
+ * different release, by a hand-run `UPDATE`, or by a host's own seeder. The
+ * same argument `WorkflowRow.nodes` makes for being typed `unknown[]`.
+ *
+ * Deliberately strict about emptiness. A `{ vault: '', keyId: '', ciphertext:
+ * '' }` is not a sealed secret and must not be treated as one — treating it as
+ * one sends it to a vault that will refuse it, and the operator is told their
+ * vault is broken when the row is. An empty ciphertext falls through as an
+ * ordinary config value instead, which is what it is.
+ *
+ * Deliberately loose about everything else, and that is the harder half to
+ * hold. `ciphertext` is tested for "non-empty string" and must never be tested
+ * for more — not base64, not a length, not a prefix. Two vaults already
+ * disagree about its shape: KMS hands back base64, Transit hands back
+ * `vault:v1:<base64>`. Any tighter check would encode one of them as the
+ * contract and start silently refusing the other's rows, which surfaces as
+ * "this credential is not encrypted" for a value that is.
+ *
+ * What it cannot distinguish is a config value a host deliberately authored as
+ * an object with exactly these three non-empty string fields. Nothing prevents
+ * that and nothing sensible produces it; saying so is better than adding a
+ * marker field that would then have to be defended against forgery it also
+ * could not detect.
+ */
+export declare function isSealedSecret(value: unknown): value is SealedSecret;
+/** The name {@link RefusingSecretVault} answers to. No row can carry it: it never seals. */
+export declare const UNCONFIGURED_VAULT = "unconfigured";
+/**
+ * The default: a vault that will not pretend.
+ *
+ * Bound whenever `CATALOG_SECRET_VAULT` is not, which is every host that has
+ * not thought about this. It costs nothing until `encryptCredentials` is turned
+ * on — the store only reaches a vault when there is something to seal or
+ * something sealed to open — so the refusal lands on the deployment that asked
+ * for encryption and did not say with what, and lands at the first save rather
+ * than at the first run.
+ *
+ * The alternative shapes were both considered and are both worse. A default
+ * that stored plaintext would make `encryptCredentials: true` a no-op with a
+ * reassuring name. A default that base64-encoded would be worse still: it looks
+ * sealed, `isSealedSecret` would agree, and a dump would be trivially reversed
+ * by anybody who noticed.
+ */
+export declare class RefusingSecretVault implements CatalogSecretVault {
+    readonly name = "unconfigured";
+    seal(_plaintext: string, context: SecretContext): Promise<SealedSecret>;
+    open(sealed: SealedSecret, context: SecretContext): Promise<string>;
+}
+/**
+ * Nothing is bound, or nothing bound answers to the name a row carries.
+ *
+ * `retryable = false`, and that field is not decoration. A connector run is
+ * dispatched as a durable step, and the dispatch boundary serialises a throw
+ * into `{message, code, retryable}` — `retryable` is the only field the engine
+ * reads on the way back in, and its predicate is `error?.retryable !== false`.
+ * A missing token will be exactly as missing on the third attempt as on the
+ * first, so this must not burn fifteen minutes of exponential backoff before
+ * saying so. `connector-run.steps.ts` documents that mechanism at length and
+ * this is the same use of it.
+ */
+export declare class SecretVaultNotConfiguredError extends Error {
+    /** The field the dispatch boundary serialises and the engine acts on. */
+    readonly retryable = false;
+    readonly code = "secret_vault_not_configured";
+    constructor(message: string);
+}
+/**
+ * A save could not seal a credential, so the save did not happen.
+ *
+ * Which is the correct outcome and worth being explicit about: the fallback a
+ * reasonable person reaches for — write it in plaintext and log a warning — is
+ * the one thing this feature exists to make impossible. A deployment that
+ * turned `encryptCredentials` on and then, during a vault outage, quietly wrote
+ * three passwords in the clear would have no way to find out which three.
+ *
+ * Deliberately not a `BadRequestException`. The caller's URL is fine; the vault
+ * is down. A 400 sends somebody to edit a field that is correct.
+ */
+export declare class SecretSealFailedError extends Error {
+    readonly code = "secret_seal_failed";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A read could not open a sealed credential.
+ *
+ * **This is the one whose class matters**, because a connector run is a durable
+ * step and the step decides whether to retry from the error it catches. Two
+ * things had to be got right here and both are load-bearing:
+ *
+ *  - It is **not** a `NotFoundException` or a `BadRequestException`.
+ *    `ConnectorRunSteps.runConnector` catches exactly those two around the
+ *    runner and converts them to `UnavailableConnectorError`, which carries
+ *    `retryable = false`. A vault that timed out would then be filed under
+ *    `connector_unavailable` and never retried — and an operator filtering a
+ *    failed-run list on that code would go looking for a connector somebody
+ *    deleted. That is precisely the confusion `UnmetLoadExpectationError` was
+ *    split into its own class to avoid.
+ *  - `retryable` is **true by default**. A vault being briefly unreachable is
+ *    the same kind of failure as a source being briefly unreachable, which is
+ *    exactly what that step's `retries: 3, backoff exp 60s…900s` policy exists
+ *    for. It is set false only when waiting provably cannot help: nothing is
+ *    bound, or nothing bound answers to the name the row carries.
+ */
+export declare class SecretOpenFailedError extends Error {
+    /** The field the dispatch boundary serialises and the engine acts on. */
+    readonly retryable: boolean;
+    readonly code = "secret_open_failed";
+    constructor(message: string, options: {
+        retryable: boolean;
+        cause?: unknown;
+    });
+}

package/dist/catalog.secrets.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * Encrypting the credential that has to rest in `catalog_connection.config`.
+ *
+ * `config-secrets.ts` in the pipeline package closed the HTTP half of this: a
+ * connection URL is a password with an address attached, `config` is served by
+ * `GET pipeline/connections` under `catalog:read`, and the redaction stopped it
+ * travelling in a response. `MySqlPipelineStore` closed the write half: a
+ * password-bearing URL that is not already stored is refused, with a message
+ * naming `secretEnvVar`.
+ *
+ * Neither touches the thing this file is about. A redaction protects a reader
+ * coming through the API. It does nothing at all for a database dump, a read
+ * replica, a nightly backup, or anybody holding `SELECT` on the RDS instance —
+ * and for those, `config` is still a list of every password the catalog knows.
+ * `allowInlineCredentials` makes that population larger on purpose, which is
+ * precisely why encryption becomes worth building at the same time as the flag
+ * that needs it.
+ *
+ * ## A seam, not an implementation
+ *
+ * There is no cipher in this file and there must not be one. A library that
+ * shipped AES with a key read from an environment variable would have moved the
+ * problem from one column to one variable, and would have to answer for key
+ * rotation, per-environment separation, and an audit trail — all of which the
+ * host's KMS, Vault, or HSM already answers for, and none of which this package
+ * can answer for on its behalf. What is here is the shape of the question, so a
+ * provider can be written against it: {@link CatalogSecretVault}.
+ *
+ * The library never inspects a ciphertext, never chooses a key, and never
+ * decides an algorithm. It decides *which values* are secrets, *when* they are
+ * sealed, and *what happens when the vault cannot be reached* — three questions
+ * a provider should not have to have an opinion about.
+ *
+ * ## What the default does
+ *
+ * Refuses. {@link RefusingSecretVault} throws on `seal`, naming the token to
+ * bind. A default that quietly stored plaintext would be the worst shape
+ * available here: a host would turn `encryptCredentials` on, see saves succeed,
+ * and have exactly the same column contents as before with a docblock now
+ * claiming otherwise. Every other refusing default in this codebase exists for
+ * the same reason — `CATALOG_LOAD_EXPECTATIONS` unbound means incremental loads
+ * are refused rather than silently unpoliced.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretOpenFailedError = exports.SecretSealFailedError = exports.SecretVaultNotConfiguredError = exports.RefusingSecretVault = exports.UNCONFIGURED_VAULT = exports.CATALOG_SECRET_VAULT = void 0;
+exports.isSealedSecret = isSealedSecret;
+/**
+ * The token a host binds one vault — or several — to.
+ *
+ * **Several is the supported shape, and it is what makes rotation possible.**
+ * Bind `CatalogSecretVault[]` and the store seals with the *first* and opens
+ * with whichever one's `name` matches the row. Moving from one vault to another
+ * is then: bind `[next, current]`, let saves reseal under `next`, and drop
+ * `current` when nothing is sealed under it any more. With a single vault that
+ * transition has no middle — the moment `next` is bound, every row sealed by
+ * `current` is unreadable — and a library that made rotation require an outage
+ * would be a library whose keys never got rotated.
+ *
+ * `@Optional()` where it is injected, so a host that binds nothing still boots.
+ * It then gets {@link RefusingSecretVault}, which costs nothing until something
+ * actually asks for a seal.
+ */
+exports.CATALOG_SECRET_VAULT = Symbol('CATALOG_SECRET_VAULT');
+/**
+ * Whether a value that came back out of a JSON column is a sealed secret.
+ *
+ * A runtime guard and not a cast, because this is a `json` column: MikroORM
+ * hands back whatever is in it, and what is in it may have been written by a
+ * different release, by a hand-run `UPDATE`, or by a host's own seeder. The
+ * same argument `WorkflowRow.nodes` makes for being typed `unknown[]`.
+ *
+ * Deliberately strict about emptiness. A `{ vault: '', keyId: '', ciphertext:
+ * '' }` is not a sealed secret and must not be treated as one — treating it as
+ * one sends it to a vault that will refuse it, and the operator is told their
+ * vault is broken when the row is. An empty ciphertext falls through as an
+ * ordinary config value instead, which is what it is.
+ *
+ * Deliberately loose about everything else, and that is the harder half to
+ * hold. `ciphertext` is tested for "non-empty string" and must never be tested
+ * for more — not base64, not a length, not a prefix. Two vaults already
+ * disagree about its shape: KMS hands back base64, Transit hands back
+ * `vault:v1:<base64>`. Any tighter check would encode one of them as the
+ * contract and start silently refusing the other's rows, which surfaces as
+ * "this credential is not encrypted" for a value that is.
+ *
+ * What it cannot distinguish is a config value a host deliberately authored as
+ * an object with exactly these three non-empty string fields. Nothing prevents
+ * that and nothing sensible produces it; saying so is better than adding a
+ * marker field that would then have to be defended against forgery it also
+ * could not detect.
+ */
+function isSealedSecret(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const vault = Reflect.get(value, 'vault');
+    const keyId = Reflect.get(value, 'keyId');
+    const ciphertext = Reflect.get(value, 'ciphertext');
+    return (typeof vault === 'string' &&
+        vault.length > 0 &&
+        typeof keyId === 'string' &&
+        typeof ciphertext === 'string' &&
+        ciphertext.length > 0);
+}
+/** The name {@link RefusingSecretVault} answers to. No row can carry it: it never seals. */
+exports.UNCONFIGURED_VAULT = 'unconfigured';
+/**
+ * The default: a vault that will not pretend.
+ *
+ * Bound whenever `CATALOG_SECRET_VAULT` is not, which is every host that has
+ * not thought about this. It costs nothing until `encryptCredentials` is turned
+ * on — the store only reaches a vault when there is something to seal or
+ * something sealed to open — so the refusal lands on the deployment that asked
+ * for encryption and did not say with what, and lands at the first save rather
+ * than at the first run.
+ *
+ * The alternative shapes were both considered and are both worse. A default
+ * that stored plaintext would make `encryptCredentials: true` a no-op with a
+ * reassuring name. A default that base64-encoded would be worse still: it looks
+ * sealed, `isSealedSecret` would agree, and a dump would be trivially reversed
+ * by anybody who noticed.
+ */
+class RefusingSecretVault {
+    name = exports.UNCONFIGURED_VAULT;
+    seal(_plaintext, context) {
+        return Promise.reject(new SecretVaultNotConfiguredError(`encryptCredentials is on, so ${context.kind}.config.${context.field} has to be sealed, and no vault is bound to seal it with. Bind CATALOG_SECRET_VAULT to a CatalogSecretVault — an AWS KMS or HashiCorp Vault provider, or your own — or turn encryptCredentials off and decide what allowInlineCredentials should be instead.`));
+    }
+    open(sealed, context) {
+        // Reachable only through a row this instance did not write, since `seal`
+        // never returns — so the useful thing to say is the name the row is asking
+        // for, which is the one the operator has to go and bind.
+        return Promise.reject(new SecretVaultNotConfiguredError(`${context.kind}.config.${context.field} was sealed by the "${sealed.vault}" vault and no vault is bound to open it. Bind CATALOG_SECRET_VAULT to that provider; nothing else can read this value.`));
+    }
+}
+exports.RefusingSecretVault = RefusingSecretVault;
+/**
+ * Nothing is bound, or nothing bound answers to the name a row carries.
+ *
+ * `retryable = false`, and that field is not decoration. A connector run is
+ * dispatched as a durable step, and the dispatch boundary serialises a throw
+ * into `{message, code, retryable}` — `retryable` is the only field the engine
+ * reads on the way back in, and its predicate is `error?.retryable !== false`.
+ * A missing token will be exactly as missing on the third attempt as on the
+ * first, so this must not burn fifteen minutes of exponential backoff before
+ * saying so. `connector-run.steps.ts` documents that mechanism at length and
+ * this is the same use of it.
+ */
+class SecretVaultNotConfiguredError extends Error {
+    /** The field the dispatch boundary serialises and the engine acts on. */
+    retryable = false;
+    code = 'secret_vault_not_configured';
+    constructor(message) {
+        super(message);
+        this.name = 'SecretVaultNotConfiguredError';
+    }
+}
+exports.SecretVaultNotConfiguredError = SecretVaultNotConfiguredError;
+/**
+ * A save could not seal a credential, so the save did not happen.
+ *
+ * Which is the correct outcome and worth being explicit about: the fallback a
+ * reasonable person reaches for — write it in plaintext and log a warning — is
+ * the one thing this feature exists to make impossible. A deployment that
+ * turned `encryptCredentials` on and then, during a vault outage, quietly wrote
+ * three passwords in the clear would have no way to find out which three.
+ *
+ * Deliberately not a `BadRequestException`. The caller's URL is fine; the vault
+ * is down. A 400 sends somebody to edit a field that is correct.
+ */
+class SecretSealFailedError extends Error {
+    code = 'secret_seal_failed';
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'SecretSealFailedError';
+    }
+}
+exports.SecretSealFailedError = SecretSealFailedError;
+/**
+ * A read could not open a sealed credential.
+ *
+ * **This is the one whose class matters**, because a connector run is a durable
+ * step and the step decides whether to retry from the error it catches. Two
+ * things had to be got right here and both are load-bearing:
+ *
+ *  - It is **not** a `NotFoundException` or a `BadRequestException`.
+ *    `ConnectorRunSteps.runConnector` catches exactly those two around the
+ *    runner and converts them to `UnavailableConnectorError`, which carries
+ *    `retryable = false`. A vault that timed out would then be filed under
+ *    `connector_unavailable` and never retried — and an operator filtering a
+ *    failed-run list on that code would go looking for a connector somebody
+ *    deleted. That is precisely the confusion `UnmetLoadExpectationError` was
+ *    split into its own class to avoid.
+ *  - `retryable` is **true by default**. A vault being briefly unreachable is
+ *    the same kind of failure as a source being briefly unreachable, which is
+ *    exactly what that step's `retries: 3, backoff exp 60s…900s` policy exists
+ *    for. It is set false only when waiting provably cannot help: nothing is
+ *    bound, or nothing bound answers to the name the row carries.
+ */
+class SecretOpenFailedError extends Error {
+    /** The field the dispatch boundary serialises and the engine acts on. */
+    retryable;
+    code = 'secret_open_failed';
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = 'SecretOpenFailedError';
+        this.retryable = options.retryable;
+    }
+}
+exports.SecretOpenFailedError = SecretOpenFailedError;

package/dist/catalog.workspace.d.ts

@@ -11,6 +11,16 @@ export interface SavedQuery {
     id: string;
     name: string;
     description?: string;
+    /**
+     * The statement, as it is now.
+     *
+     * Overwritten in place by {@link CatalogWorkspaceStore.updateSavedQuery}, and
+     * for a long time that was the end of it — a report that started answering
+     * differently left nothing to compare against, not even a version number. What
+     * it used to say is kept as {@link CatalogRevision}s now, read through
+     * {@link CatalogWorkspaceStore.listSavedQueryRevisions}; this field stays the
+     * one a run of the query executes.
+     */
     sql: string;
     /** Free-form grouping, the way a folder would work without being one. */
     folder?: string;
@@ -71,6 +81,122 @@ export interface SaveQueryInput {
     visualization?: QueryVisualization;
     shared?: boolean;
 }
+/**
+ * One recorded revision of something whose text a person edits.
+ *
+ * The same shape for a transform's code and for a saved query's SQL, and that is
+ * the point rather than a saving: the two are edited the same way and go wrong
+ * the same way — somebody changes the text, a load or a report starts coming out
+ * different, and the question afterwards is what the text used to say. `body` is
+ * named for that. `code` would have been a lie on half of its uses.
+ *
+ * ## What this exists to fix
+ *
+ * A {@link ConnectorRun} has always recorded `transformVersion`, so the catalog
+ * already knew *which* version produced a given load. What it did not keep was
+ * the text of that version: one row per transform, overwritten in place, the
+ * counter bumped and the previous code gone. A saved query had not even the
+ * counter. Meanwhile the runs list renders `code v3`, which reads as a reference
+ * to something retrievable — so an operator was told a version number, believed
+ * the source was recoverable, and it was not.
+ *
+ * The number on the run and the {@link version} here are **the same number**.
+ * That is the whole contract: "this load ran v3" becomes something a person can
+ * open.
+ *
+ * ## No `kind` field, deliberately
+ *
+ * A revision is always read through a route that already names its subject —
+ * `transforms/:id/revisions`, `saved-queries/:id/revisions` — so a discriminator
+ * here would be a field whose only possible value the caller had just supplied.
+ * The *store* keys by one, because one table holds both kinds; that is a storage
+ * concern and it stays in the store.
+ *
+ * ## What is NOT revisioned, and why
+ *
+ * A workflow graph, which has the identical "latest only" limitation and is
+ * deliberately left with it. See {@link CatalogWorkflow}, which makes the
+ * argument where somebody looking for the missing feature will find it.
+ */
+export interface CatalogRevision {
+    /**
+     * Stable id of this revision.
+     *
+     * Derived from the subject and the version rather than random — see
+     * `revisionKey` in the MikroORM store — so recording the same version twice
+     * replaces it instead of appending a second copy, and a screen may key a list
+     * on it across refetches.
+     */
+    id: string;
+    /** What it belongs to — a transform id or a saved-query id. */
+    subjectId: string;
+    /** The version this revision IS. Matches `transformVersion` on a run. */
+    version: number;
+    /** The text as it was: the transform's code, or the query's SQL. */
+    body: string;
+    /**
+     * Who saved it.
+     *
+     * Exact for a transform, which is saved through a store method that is given
+     * the actor. **Approximate for a saved query**, whose update path is given
+     * none — `updateSavedQuery` takes an id and a patch, and `CatalogService`
+     * keeps the actor for the audit event it emits — so a saved query's revisions
+     * are attributed to the query's `createdBy`. That is who created it, not
+     * necessarily who last edited it, and it is recorded that way rather than
+     * invented: a name here that was picked to fill the field would be read as
+     * evidence. Threading the editor through `updateSavedQuery` is what would fix
+     * it, and it is a change to that method's contract rather than to this one.
+     */
+    authoredBy: string;
+    authoredAt: string;
+}
+/**
+ * How many revisions are kept per subject. Writing a newer one drops the oldest
+ * beyond this.
+ *
+ * ## Why there is a cap at all
+ *
+ * This is append-only text that grows forever, and it is the fourth append-only
+ * table in the bundled store. The other three earn their unboundedness and this
+ * one does not. An audit event and a connector run are each one small row per
+ * *thing that happened*, at a rate an operator can read off their own load
+ * schedule; staged rows are dropped the moment the run that produced them is
+ * finished with. A revision is neither: it grows with how often somebody edits,
+ * which nobody meters, and every row carries a whole code body rather than a
+ * counter. Unpredictable in rate *and* large per row is the combination worth
+ * bounding — and "this grows; here is the query to prune it" would have been a
+ * fourth unbounded table with a paragraph in front of it.
+ *
+ * ## Why a count per subject rather than an age bound
+ *
+ * An age bound keys the wrong thing. A transform edited twice in 2019 and relied
+ * on ever since would lose both revisions, while one edited daily keeps
+ * everything — exactly backwards. What makes a revision unrecoverable is being
+ * superseded, so that is what the bound counts.
+ *
+ * ## What it costs, stated rather than implied
+ *
+ * A run's `transformVersion` can name a revision that has been evicted: a
+ * transform saved more than this many times can no longer produce its earliest
+ * code. That loss is real. It is strictly smaller than the one it replaces —
+ * where every version but the newest was unrecoverable — and it is visible
+ * rather than silent, because a caller holding a version older than the oldest
+ * revision in the list can see that the list does not reach that far.
+ *
+ * At the cap a 4 KB body costs 200 KB per subject, so a thousand heavily-edited
+ * subjects cost roughly 200 MB. That is a ceiling, which is the point of having
+ * one.
+ *
+ * ## Why a constant and not a module option
+ *
+ * The number is part of what this table promises, and a console should be able
+ * to print "the last 50 are kept" without a round trip to ask which deployment
+ * it is talking to. A knob is also a promise to support every value of it,
+ * including the one that switches the feature off and is then reported as a bug.
+ * It becomes an option on the day there is a deployment it is wrong for, rather
+ * than in anticipation of one.
+ */
+export declare const CATALOG_REVISION_LIMIT = 50;
 export interface Dashboard {
     id: string;
     name: string;
@@ -480,6 +606,26 @@ export interface CatalogWorkspaceStore {
      * first and decides.
      */
     deleteSavedQuery(id: string): Promise<boolean>;
+    /**
+     * Every SQL this saved query has ever been, newest first.
+     *
+     * **Optional**, and mixed in here rather than made a member every store must
+     * have, for the reason {@link CatalogWorkflowStore} gives about the same
+     * decision: a store written against the previous shape of this interface —
+     * including the routing proxy in the MikroORM package — implements
+     * `CatalogWorkspaceStore` today, and turning that into a compile error would
+     * be a breaking change for a feature that is purely additive.
+     * {@link supportsSavedQueryRevisions} is how a caller asks, so "this store
+     * keeps no revisions" is a sentence a route can say rather than a method that
+     * is missing at run time.
+     *
+     * An EMPTY list is a real answer and never an error: a query nobody has edited
+     * since this shipped may genuinely have nothing recorded. What the bundled
+     * store does about that — see `readRevisions` — is a store's decision, and a
+     * consumer must read "nothing recorded" as itself rather than as "nothing has
+     * changed".
+     */
+    listSavedQueryRevisions?(id: string): Promise<CatalogRevision[]>;
     listDashboards(): Promise<Dashboard[]>;
     getDashboard(id: string): Promise<Dashboard | undefined>;
     saveDashboard(input: {
@@ -498,5 +644,13 @@ export interface CatalogWorkspaceStore {
     recordEvent(event: Omit<CatalogAuditEvent, 'id'>): Promise<void>;
     listEvents(query: AuditQuery): Promise<CatalogAuditEvent[]>;
 }
+/**
+ * Whether this store keeps a saved query's history.
+ *
+ * Checks the method rather than a flag, the same way {@link isWorkspaceStore}
+ * and `supportsWorkflows` do: a flag is a claim and a method is the thing
+ * itself.
+ */
+export declare function supportsSavedQueryRevisions(store: CatalogWorkspaceStore): store is CatalogWorkspaceStore & Required<Pick<CatalogWorkspaceStore, 'listSavedQueryRevisions'>>;
 export declare function isWorkspaceStore(store: unknown): store is CatalogWorkspaceStore;
 export declare const CATALOG_WORKSPACE_STORE: unique symbol;