@dudousxd/nestjs-catalog 0.9.0 → 0.11.0

package/dist/catalog.registry.js

@@ -179,7 +179,7 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
         return this.entityClasses.get(name);
     }
     /** Tier-0 edit on a type. Never touches the database. */
-    async patchType(typeName, patch) {
+    async patchType(typeName, patch, curatedBy) {
         const type = this.getType(typeName);
         if (!type)
             return undefined;
@@ -192,11 +192,15 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
         (0, catalog_events_1.emitCatalog)('type.curated', {
             typeName: type.name,
             changed: Object.keys(rest),
+            // Through `curationActor` rather than passed straight in, even though the
+            // parameter is required: the callers this class actually has to survive are
+            // the ones the compiler never saw. See the note on that function.
+            principalId: (0, catalog_events_1.curationActor)(curatedBy),
         });
         return this.getType(type.name);
     }
     /** Tier-0 edit on a property. Never touches the database. */
-    async patchProperty(typeName, propertyName, patch) {
+    async patchProperty(typeName, propertyName, patch, curatedBy) {
         const type = this.getType(typeName);
         if (!type)
             return undefined;
@@ -218,6 +222,7 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
             typeName: type.name,
             property: propertyName,
             changed: Object.keys(patch),
+            principalId: (0, catalog_events_1.curationActor)(curatedBy),
         });
         return this.getType(type.name);
     }
@@ -231,12 +236,18 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
      *
      * Emitted after the write, like the two patches above, so the trail says what
      * happened rather than what was about to.
+     *
+     * The actor is applied here rather than inside {@link summariseOverlay}, which
+     * stays a pure function of the overlay. What was destroyed and who destroyed it
+     * are facts from two different places, and folding the principal into the
+     * summariser would mean the one function that must be callable with nothing but
+     * an old overlay suddenly needing the request as well.
      */
-    async resetOverlay() {
+    async resetOverlay(resetBy) {
         const discarded = summariseOverlay(this.overlay);
         this.overlay = { types: {} };
         await this.persist();
-        (0, catalog_events_1.emitCatalog)('overlay.reset', discarded);
+        (0, catalog_events_1.emitCatalog)('overlay.reset', { ...discarded, principalId: (0, catalog_events_1.curationActor)(resetBy) });
     }
     async persist() {
         await this.overlayStore.save(this.overlay);
@@ -390,6 +401,13 @@ exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry = MikroOrmCatalogRegis
  * order is forced: a caller has to hold the old overlay to call it, and cannot
  * accidentally summarise the empty one it just installed.
  *
+ * Everything the payload holds except the actor, stated as an `Omit` of the
+ * payload rather than a shape of its own. A hand-written interface here would be
+ * a second copy of the contract, free to fall behind the day a field is added —
+ * and the failure would be a summary silently missing a key that the type says
+ * is required. `principalId` is the caller's to supply because it is a fact about
+ * the request, not about the overlay.
+ *
  * A type entry counts whatever it holds, including an entry that ended up empty.
  * `buildType` treats a present entry as enrichment on the same terms, and the
  * honest reading of one is "somebody patched this type" — which is exactly what

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.service.d.ts

@@ -27,11 +27,26 @@ export declare class CatalogService {
     getType(name: string): CatalogObjectTypeDef | undefined;
     /** Nodes and edges, for drawing the model. */
     getGraph(): CatalogGraph;
-    /** Presentation-only. Never a schema change. */
-    patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
-    patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
-    /** Drops every runtime edit, where the registry supports it. */
-    resetOverlay(): Promise<void>;
+    /**
+     * Presentation-only. Never a schema change.
+     *
+     * @param curatedBy who is doing it, for the audit trail — the same required
+     * argument the sharing methods below take, and required for the same reason
+     * `deleteSavedQuery` gives. This facade forwards it rather than resolving it:
+     * a host writing its own controller has the request and this does not, and a
+     * default here would attribute every such host's curation to nobody.
+     */
+    patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>, curatedBy: string): Promise<CatalogObjectTypeDef | undefined>;
+    /** @param curatedBy who is doing it, for the audit trail. */
+    patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string], curatedBy: string): Promise<CatalogObjectTypeDef | undefined>;
+    /**
+     * Drops every runtime edit, where the registry supports it.
+     *
+     * @param resetBy who is doing it. The one act here that destroys curation in
+     * bulk, so it is the one whose actor is hardest to reconstruct afterwards —
+     * nothing versions an overlay, and after this there is nothing left to read.
+     */
+    resetOverlay(resetBy: string): Promise<void>;
     /** Columns a generic UI may render: visible, and not a blob. */
     visibleColumns(type: CatalogObjectTypeDef): import("./catalog.types").CatalogPropertyDef[];
     /**

package/dist/catalog.service.js

@@ -66,16 +66,31 @@ let CatalogService = class CatalogService {
     getGraph() {
         return this.registry.getGraph();
     }
-    /** Presentation-only. Never a schema change. */
-    patchType(typeName, patch) {
-        return this.registry.patchType(typeName, patch);
+    /**
+     * Presentation-only. Never a schema change.
+     *
+     * @param curatedBy who is doing it, for the audit trail — the same required
+     * argument the sharing methods below take, and required for the same reason
+     * `deleteSavedQuery` gives. This facade forwards it rather than resolving it:
+     * a host writing its own controller has the request and this does not, and a
+     * default here would attribute every such host's curation to nobody.
+     */
+    patchType(typeName, patch, curatedBy) {
+        return this.registry.patchType(typeName, patch, curatedBy);
     }
-    patchProperty(typeName, propertyName, patch) {
-        return this.registry.patchProperty(typeName, propertyName, patch);
+    /** @param curatedBy who is doing it, for the audit trail. */
+    patchProperty(typeName, propertyName, patch, curatedBy) {
+        return this.registry.patchProperty(typeName, propertyName, patch, curatedBy);
     }
-    /** Drops every runtime edit, where the registry supports it. */
-    resetOverlay() {
-        return this.registry.resetOverlay();
+    /**
+     * Drops every runtime edit, where the registry supports it.
+     *
+     * @param resetBy who is doing it. The one act here that destroys curation in
+     * bulk, so it is the one whose actor is hardest to reconstruct afterwards —
+     * nothing versions an overlay, and after this there is nothing left to read.
+     */
+    resetOverlay(resetBy) {
+        return this.registry.resetOverlay(resetBy);
     }
     /** Columns a generic UI may render: visible, and not a blob. */
     visibleColumns(type) {

package/dist/client.d.ts

@@ -93,5 +93,6 @@ export { CONNECTOR_KINDS, isConnectorKind, isTransformLanguage, isWorkflowEdge,
  * `WORKFLOW_NODE_ID_PATTERN` and `WORKFLOW_NODE_KINDS` are what a palette and an
  * id field should be built from rather than from a second copy that drifts.
  */
-export { validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, workflowGraphHash, workflowRunOrder, isWorkflowExecutionMode, isWorkflowNodeKind, } from './catalog.pipeline';
+export { validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, workflowGraphHash, workflowRunOrder, isWorkflowExecutionMode, isWorkflowNodeKind, isWorkflowStatus, } from './catalog.pipeline';
+export type { WorkflowStatus } from './catalog.pipeline';
 export type { CatalogTrace, CatalogTraceList, CatalogTraceOutcome, CatalogTraceSpan, TraceQuery, } from './catalog.workspace';