@dudousxd/nestjs-catalog 0.11.0 → 0.13.0

package/dist/catalog.store.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_STORE = exports.CatalogColumnCollisionError = exports.CATALOG_RESERVED_COLUMNS = exports.CATALOG_SNAPSHOT_MODES = void 0;
+exports.CATALOG_STORE = exports.CatalogColumnCollisionError = exports.UnsafeIdentifierError = exports.CATALOG_RESERVED_COLUMNS = exports.CATALOG_SNAPSHOT_MODES = void 0;
 exports.isCatalogStoreCapabilities = isCatalogStoreCapabilities;
 exports.isReservedColumn = isReservedColumn;
+exports.isSafeIdentifier = isSafeIdentifier;
+exports.assertSafeIdentifier = assertSafeIdentifier;
 exports.findColumnCollisions = findColumnCollisions;
 exports.assertNoColumnCollisions = assertNoColumnCollisions;
 exports.isWriteStore = isWriteStore;
@@ -72,6 +74,73 @@ exports.CATALOG_RESERVED_COLUMNS = [
 function isReservedColumn(column) {
     return exports.CATALOG_RESERVED_COLUMNS.some((reserved) => reserved === column.toLowerCase());
 }
+/**
+ * What a name has to look like before a store will write it into SQL.
+ *
+ * Identifiers are *rejected*, never escaped and never sanitised. Every table
+ * and column name a store emits arrives from another application over HTTP and
+ * ends up in DDL and in SELECT lists, where no placeholder can stand in for it,
+ * so anything outside this character set never becomes SQL at all.
+ *
+ * Here, beside {@link CATALOG_RESERVED_COLUMNS}, for the same reason: it is
+ * part of what the catalog promises a *publisher*. Refuse a property name and
+ * the sentence explaining why is the only statement of the rule most people
+ * will ever read, so it belongs to the contract rather than to whichever
+ * adapter happens to be mounted.
+ *
+ * And for one more reason. It used to be two copies — `store-mikro-orm` and
+ * `store-clickhouse` each carried this pattern and this sentence, byte for
+ * byte — and the publish-time refusal in the pipeline package borrowed the
+ * MySQL one so that publish-time and DDL-time could not disagree about the
+ * character set, the length or the wording. That bought the guarantee for a
+ * MySQL deployment and left a ClickHouse-only one trusting two files to be
+ * edited together. One definition is the guarantee; two identical ones are a
+ * habit.
+ *
+ * 63 characters because it is under MySQL's 64-character ceiling and no engine
+ * a store here targets refuses a name that short, and because the number is
+ * quoted in the refusal below: a per-store limit would mean a publisher being
+ * told a different rule depending on what is mounted, for a name the catalog
+ * would then be unable to promise anything about across a fan-out.
+ *
+ * Not exported. A `RegExp` is mutable and shared state, and the two questions
+ * anyone has of it — "may I?" and "why not?" — are {@link isSafeIdentifier} and
+ * {@link UnsafeIdentifierError}.
+ */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+/**
+ * Why a name cannot be written into SQL, in the words a publisher is given.
+ *
+ * One class for the whole ecosystem rather than one per adapter, so
+ * `instanceof` is a usable question across packages. The publish-time check in
+ * the pipeline package catches this to tell "that name cannot be an identifier"
+ * from "something else failed inside the store", and with a class per adapter
+ * that check would re-throw the moment the mounted store was not the one it
+ * imported — turning a 400 that names the property into a 500 that names
+ * nothing.
+ */
+class UnsafeIdentifierError extends Error {
+    constructor(value) {
+        super(`Refusing to use "${value}" as a SQL identifier: letters, digits and underscore only, starting with a letter or underscore, 63 characters max.`);
+    }
+}
+exports.UnsafeIdentifierError = UnsafeIdentifierError;
+/** Whether a name can be written into SQL as it stands. */
+function isSafeIdentifier(value) {
+    return SAFE_IDENTIFIER.test(value);
+}
+/**
+ * Refuse a name that cannot be a SQL identifier.
+ *
+ * Throws rather than answering, because the caller's next line writes the value
+ * into a statement: a boolean that can be ignored is a boolean that eventually
+ * is. {@link isSafeIdentifier} is there for the callers that are asking rather
+ * than about to build.
+ */
+function assertSafeIdentifier(value) {
+    if (!isSafeIdentifier(value))
+        throw new UnsafeIdentifierError(value);
+}
 /**
  * Every way a type's properties would fight over a physical column.
  *

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;

package/dist/catalog.workspace.js

@@ -9,12 +9,60 @@
  * mount the catalog without any of this and notice nothing missing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = void 0;
+exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.CATALOG_REVISION_LIMIT = void 0;
 exports.isCatalogTraceOutcome = isCatalogTraceOutcome;
 exports.traceOutcomeFilter = traceOutcomeFilter;
 exports.isTraceStore = isTraceStore;
 exports.embeddedVisualization = embeddedVisualization;
+exports.supportsSavedQueryRevisions = supportsSavedQueryRevisions;
 exports.isWorkspaceStore = isWorkspaceStore;
+/**
+ * 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.
+ */
+exports.CATALOG_REVISION_LIMIT = 50;
 /**
  * The same events, told as stories instead of as a list.
  *
@@ -102,6 +150,16 @@ function embeddedVisualization(saved, cardLibrary) {
     const base = saved ?? { kind: 'table' };
     return cardLibrary ? { ...base, library: cardLibrary } : base;
 }
+/**
+ * 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.
+ */
+function supportsSavedQueryRevisions(store) {
+    return typeof store.listSavedQueryRevisions === 'function';
+}
 function isWorkspaceStore(store) {
     return (typeof store === 'object' &&
         store !== null &&

package/dist/client.d.ts

@@ -9,7 +9,9 @@
  * own UI. The endpoints alone are not an API; the endpoints plus the response
  * types are.
  */
-export type { AuditQuery, CatalogAuditEvent, Dashboard, DashboardCard, QueryVisualization, SaveQueryInput, SavedQuery, } from './catalog.workspace';
+import type { DeleteReconciliation, LoadExpectation, RowCountBound, StoredLoadExpectation } from './catalog.pipeline';
+export type { AuditQuery, CatalogAuditEvent, CatalogRevision, Dashboard, DashboardCard, QueryVisualization, SaveQueryInput, SavedQuery, } from './catalog.workspace';
+export { CATALOG_REVISION_LIMIT } from './catalog.workspace';
 export type { CatalogQueryRelation, CatalogQueryRequest, CatalogQueryResult, } from './catalog.query';
 export type { CatalogSearchField, CatalogSearchHit, CatalogSearchKind, CatalogSearchRank, CatalogSearchResult, } from './search.types';
 export type { CatalogGraph, CatalogObjectPage, CatalogObjectQuery, CatalogObjectTypeDef, CatalogOverlay, CatalogPropertyDef, CatalogRelationDef, CatalogSnapshot, RelationKind, ScalarType, } from './catalog.types';
@@ -66,6 +68,15 @@ export declare const catalogRoutes: {
     readonly workspaceCapabilities: () => string;
     readonly savedQueries: () => string;
     readonly savedQuery: (id: string) => string;
+    /**
+     * Every SQL this query has ever been.
+     *
+     * A sub-resource of the saved query rather than a `?version=` on it, because
+     * the question a diff screen asks first is "what were all of them" — it has to
+     * see the list before it knows which two to compare, and one request that
+     * answers that beats a list plus two fetches.
+     */
+    readonly savedQueryRevisions: (id: string) => string;
     readonly runSavedQuery: (id: string) => string;
     readonly exportSavedQuery: (id: string) => string;
     readonly dashboards: () => string;
@@ -96,3 +107,111 @@ export { CONNECTOR_KINDS, isConnectorKind, isTransformLanguage, isWorkflowEdge,
 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';
+export type { CatalogLoadExpectations, DeleteReconciliation, LoadExpectation, RowCountBound, StoredLoadExpectation, } from './catalog.pipeline';
+/**
+ * The three answers to "how do deletions at the source reach this type", as a
+ * value.
+ *
+ * A list rather than only the union, because the editor on the Model screen has
+ * to offer them and a hand-written array in a component is the copy that drifts
+ * — the same argument {@link CONNECTOR_KINDS} makes one screen over. The server
+ * validates against this too: a `strategy` off the wire is `string` until
+ * something checks it, and the check and the dropdown reading one list is what
+ * stops the two from disagreeing about what is acceptable.
+ *
+ * **There are three and there is deliberately no fourth.** Tombstones off a
+ * change feed is the correct answer and needs machinery nothing here has; a
+ * strategy name that nothing implements is a dropdown with a lie in it. See
+ * `DeleteReconciliation` for the whole argument.
+ */
+export declare const DELETE_RECONCILIATION_STRATEGIES: readonly ["accepted", "soft-deleted-at-source", "periodic-full-reload"];
+export type DeleteReconciliationStrategy = (typeof DELETE_RECONCILIATION_STRATEGIES)[number];
+/** Whether a value off the wire names one of the three. */
+export declare function isDeleteReconciliationStrategy(value: unknown): value is DeleteReconciliationStrategy;
+/**
+ * What an operator sends to set a type's expectation.
+ *
+ * Both fields optional and both meaning "leave this alone" when absent, which is
+ * why they are not simply `LoadExpectation`: a request that omits `rowCount`
+ * has said nothing about row counts, and reading that as "clear it" would let a
+ * form that only renders the delete strategy silently drop a bound somebody set.
+ * Clearing the whole stored row is `DELETE`, which is a decision with a verb on
+ * it.
+ */
+export interface LoadExpectationInput {
+    deletes?: DeleteReconciliation;
+    rowCount?: Partial<RowCountBound>;
+}
+/**
+ * The resolved expectation for one type, and which layer won each field.
+ *
+ * The provenance is the whole reason this is not just a `LoadExpectation`. The
+ * policy is sourced from three layers — `host.byType[type]`, then the stored row
+ * an operator set, then `host.default` — and a screen that showed only the
+ * answer would let somebody edit a field this deployment has pinned in code and
+ * watch the edit vanish on the next read, with nothing anywhere saying why.
+ * {@link hostLocked} is what lets it say "this deployment fixed it" instead.
+ */
+export interface ResolvedLoadExpectation {
+    typeName: string;
+    /** The three layers merged, field by field. What the load is actually judged against. */
+    resolved: LoadExpectation;
+    /**
+     * Which layer supplied the delete strategy.
+     *
+     * `'default'` means the host's house-wide `default` did. `'none'` means
+     * nothing did, anywhere — which is not a gap to be filled in silently: it is
+     * the state that refuses every incremental load of this type, and the one the
+     * screen most needs to name.
+     */
+    deletesFrom: 'host' | 'stored' | 'default' | 'none';
+    /**
+     * Which layer supplied the row-count bound — the strongest one that set any
+     * field of it, since the three are merged key by key rather than replaced
+     * whole.
+     *
+     * There is no `'none'`, and that is a statement rather than an omission: a
+     * bound always applies. Where no layer says anything the built-in
+     * `DEFAULT_ROW_COUNT_BOUND` does, and that is what `'default'` covers as well
+     * as the host's own `default`.
+     */
+    rowCountFrom: 'host' | 'stored' | 'default';
+    /** The operator's row, present whether or not it won anything. */
+    stored?: StoredLoadExpectation;
+    /**
+     * Which fields this deployment declared in code, per field.
+     *
+     * True means a stored value for that field would never apply, so the editor
+     * shows it disabled and says so. Only `host.byType[type]` locks: `host.default`
+     * is the weakest layer and an operator's row beats it, so a house-wide default
+     * is not a lock and must not be drawn as one.
+     */
+    hostLocked: {
+        deletes: boolean;
+        rowCount: boolean;
+    };
+}
+/**
+ * Where the per-type expectations sit, relative to wherever the pipeline
+ * controller was mounted.
+ *
+ * A function of the base path rather than a frozen object like
+ * {@link catalogRoutes}, and the difference is the one `routes.ts` in the React
+ * package draws: the catalog controller's paths cannot move, and these move with
+ * whatever `path` the host passed to `CatalogPipelineModule.forRoot` — the
+ * routes below are `<path>/pipeline/expectations`, and `/pipeline` is only the
+ * default.
+ *
+ * Two builders for four routes: `PUT` and `DELETE` address the same path a `GET`
+ * of one type does, and a builder per verb would be three names for one string.
+ */
+export declare function pipelineExpectationRoutes(basePath?: string): {
+    /** Every stored row, plus the types the host has locked. `GET`, `catalog:read`. */
+    readonly expectations: () => string;
+    /**
+     * One type: `GET` for the resolved expectation and its provenance, `PUT` to
+     * set the stored row, `DELETE` to drop it. The writes need `catalog:curate`
+     * and a signed-in person.
+     */
+    readonly expectation: (typeName: string) => string;
+};

package/dist/client.js

@@ -11,7 +11,14 @@
  * types are.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = void 0;
+exports.DELETE_RECONCILIATION_STRATEGIES = exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = exports.CATALOG_REVISION_LIMIT = void 0;
+exports.isDeleteReconciliationStrategy = isDeleteReconciliationStrategy;
+exports.pipelineExpectationRoutes = pipelineExpectationRoutes;
+// A value, not a type: a screen saying how far back the history goes should read
+// the number rather than print one of its own. See its docblock for what the cap
+// costs.
+var catalog_workspace_1 = require("./catalog.workspace");
+Object.defineProperty(exports, "CATALOG_REVISION_LIMIT", { enumerable: true, get: function () { return catalog_workspace_1.CATALOG_REVISION_LIMIT; } });
 /**
  * Builds the paths the catalog controller serves, relative to wherever it was
  * mounted. Kept as string builders rather than a fetch wrapper so the host
@@ -40,6 +47,15 @@ exports.catalogRoutes = {
     workspaceCapabilities: () => '/catalog/workspace/capabilities',
     savedQueries: () => '/catalog/saved-queries',
     savedQuery: (id) => `/catalog/saved-queries/${encodeURIComponent(id)}`,
+    /**
+     * Every SQL this query has ever been.
+     *
+     * A sub-resource of the saved query rather than a `?version=` on it, because
+     * the question a diff screen asks first is "what were all of them" — it has to
+     * see the list before it knows which two to compare, and one request that
+     * answers that beats a list plus two fetches.
+     */
+    savedQueryRevisions: (id) => `/catalog/saved-queries/${encodeURIComponent(id)}/revisions`,
     runSavedQuery: (id) => `/catalog/saved-queries/${encodeURIComponent(id)}/run`,
     exportSavedQuery: (id) => `/catalog/saved-queries/${encodeURIComponent(id)}/export.csv`,
     dashboards: () => '/catalog/dashboards',
@@ -99,3 +115,56 @@ Object.defineProperty(exports, "workflowRunOrder", { enumerable: true, get: func
 Object.defineProperty(exports, "isWorkflowExecutionMode", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowExecutionMode; } });
 Object.defineProperty(exports, "isWorkflowNodeKind", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowNodeKind; } });
 Object.defineProperty(exports, "isWorkflowStatus", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowStatus; } });
+/**
+ * The three answers to "how do deletions at the source reach this type", as a
+ * value.
+ *
+ * A list rather than only the union, because the editor on the Model screen has
+ * to offer them and a hand-written array in a component is the copy that drifts
+ * — the same argument {@link CONNECTOR_KINDS} makes one screen over. The server
+ * validates against this too: a `strategy` off the wire is `string` until
+ * something checks it, and the check and the dropdown reading one list is what
+ * stops the two from disagreeing about what is acceptable.
+ *
+ * **There are three and there is deliberately no fourth.** Tombstones off a
+ * change feed is the correct answer and needs machinery nothing here has; a
+ * strategy name that nothing implements is a dropdown with a lie in it. See
+ * `DeleteReconciliation` for the whole argument.
+ */
+exports.DELETE_RECONCILIATION_STRATEGIES = [
+    'accepted',
+    'soft-deleted-at-source',
+    'periodic-full-reload',
+];
+/** Whether a value off the wire names one of the three. */
+function isDeleteReconciliationStrategy(value) {
+    return (typeof value === 'string' &&
+        exports.DELETE_RECONCILIATION_STRATEGIES.includes(value));
+}
+/**
+ * Where the per-type expectations sit, relative to wherever the pipeline
+ * controller was mounted.
+ *
+ * A function of the base path rather than a frozen object like
+ * {@link catalogRoutes}, and the difference is the one `routes.ts` in the React
+ * package draws: the catalog controller's paths cannot move, and these move with
+ * whatever `path` the host passed to `CatalogPipelineModule.forRoot` — the
+ * routes below are `<path>/pipeline/expectations`, and `/pipeline` is only the
+ * default.
+ *
+ * Two builders for four routes: `PUT` and `DELETE` address the same path a `GET`
+ * of one type does, and a builder per verb would be three names for one string.
+ */
+function pipelineExpectationRoutes(basePath = '/pipeline') {
+    const base = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+    return {
+        /** Every stored row, plus the types the host has locked. `GET`, `catalog:read`. */
+        expectations: () => `${base}/expectations`,
+        /**
+         * One type: `GET` for the resolved expectation and its provenance, `PUT` to
+         * set the stored row, `DELETE` to drop it. The writes need `catalog:curate`
+         * and a signed-in person.
+         */
+        expectation: (typeName) => `${base}/expectations/${encodeURIComponent(typeName)}`,
+    };
+}

package/dist/index.d.ts

@@ -8,17 +8,17 @@ export { type CatalogOverlayStore, FileCatalogOverlayStore, InMemoryCatalogOverl
 export { CATALOG_OVERLAY_STORE } from './catalog.overlay-store.token';
 export { MikroOrmCatalogRegistry } from './catalog.registry';
 export { CatalogRegistry } from './catalog.registry.base';
-export { CATALOG_PIPELINE_STORE, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type ConnectorKind, type ConnectorRun, isConnectorKind, isPipelineStore, isTransformLanguage, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowNode, isWorkflowNodeKind, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowGraph, workflowGraphHash, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, type WorkflowNodeOutcome, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
+export { CATALOG_PIPELINE_STORE, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogLoadExpectations, type CatalogLoadExpectationStore, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type ConnectorKind, type ConnectorRun, type DeleteReconciliation, isConnectorKind, isPipelineStore, isTransformLanguage, type LoadExpectation, type RowCountBound, type StoredLoadExpectation, supportsLoadExpectations, supportsTransformRevisions, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowNode, isWorkflowNodeKind, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowGraph, workflowGraphHash, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, type WorkflowNodeOutcome, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
 export * from './catalog.environment';
 export { QueryCache, toCsv } from './catalog.query-cache';
 export { SubprocessTransformRunner, type TransformRunnerOptions, } from './transform-runner';
 export { CatalogService } from './catalog.service';
 export { DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT, bestMatch, emptySearch, maySearch, type SearchInput, type SearchableDashboard, type SearchableSavedQuery, searchCatalog, visibleToPrincipal, } from './search';
 export type { CatalogSearchField, CatalogSearchHit, CatalogSearchKind, CatalogSearchRank, CatalogSearchResult, } from './search.types';
-export { type AuditQuery, CATALOG_TRACE_OUTCOMES, CATALOG_TRACE_STORE, CATALOG_WORKSPACE_STORE, type CatalogAuditEvent, type CatalogTrace, type CatalogTraceList, type CatalogTraceOutcome, type CatalogTraceSpan, type CatalogTraceStore, type CatalogTraceTotals, type CatalogUnlinkedList, type CatalogWorkspaceStore, type Dashboard, type DashboardCard, type EmbeddedChart, type EmbeddedChartPlacement, type EmbeddedDashboard, embeddedVisualization, isCatalogTraceOutcome, isTraceStore, isWorkspaceStore, type QueryVisualization, type SaveQueryInput, type SavedQuery, type TraceQuery, traceOutcomeFilter, } from './catalog.workspace';
+export { type AuditQuery, CATALOG_REVISION_LIMIT, CATALOG_TRACE_OUTCOMES, CATALOG_TRACE_STORE, CATALOG_WORKSPACE_STORE, type CatalogAuditEvent, type CatalogRevision, type CatalogTrace, type CatalogTraceList, type CatalogTraceOutcome, type CatalogTraceSpan, type CatalogTraceStore, type CatalogTraceTotals, type CatalogUnlinkedList, type CatalogWorkspaceStore, type Dashboard, type DashboardCard, type EmbeddedChart, type EmbeddedChartPlacement, type EmbeddedDashboard, embeddedVisualization, isCatalogTraceOutcome, isTraceStore, isWorkspaceStore, type QueryVisualization, type SaveQueryInput, type SavedQuery, supportsSavedQueryRevisions, type TraceQuery, traceOutcomeFilter, } from './catalog.workspace';
 export { CATALOG_PRINCIPAL_RESOLVER, type CatalogActor, type CatalogGrants, type CatalogPrincipal, type CatalogPrincipalResolver, type CatalogScope, composePrincipalId, delegatePrincipal, expandScopes, hasScope, parsePrincipalId, PRINCIPAL_ACTOR_SEPARATOR, maySeeClassification, mayRead, mayWrite, readableObjectPage, StaticKeyPrincipalResolver, } from './catalog.principal';
 export * from './catalog.access';
-export { assertNoColumnCollisions, CATALOG_RESERVED_COLUMNS, CATALOG_SNAPSHOT_MODES, CATALOG_STORE, type CarryForwardResult, type CatalogColumnCollision, CatalogColumnCollisionError, type CatalogMergeStore, type CatalogReadQuery, type CatalogReadResult, type CatalogReadStore, type CatalogReservedColumn, type CatalogSnapshotMode, type CatalogStoreCapabilities, type CatalogWriteStore, type ColumnCollisionOptions, findColumnCollisions, isCatalogStoreCapabilities, isReservedColumn, isWriteStore, type SnapshotRef, supportsCarryForward, } from './catalog.store';
+export { assertNoColumnCollisions, assertSafeIdentifier, CATALOG_RESERVED_COLUMNS, CATALOG_SNAPSHOT_MODES, CATALOG_STORE, type CarryForwardResult, type CatalogColumnCollision, CatalogColumnCollisionError, type CatalogMergeStore, type CatalogReadQuery, type CatalogReadResult, type CatalogReadStore, type CatalogReservedColumn, type CatalogSnapshotMode, type CatalogStoreCapabilities, type CatalogWriteStore, type ColumnCollisionOptions, findColumnCollisions, isCatalogStoreCapabilities, isReservedColumn, isSafeIdentifier, isWriteStore, type SnapshotRef, supportsCarryForward, UnsafeIdentifierError, } from './catalog.store';
 export { MikroOrmReadStore } from './stores/mikro-orm-read.store';
 export type { CatalogGraph, CatalogObjectPage, CatalogObjectQuery, CatalogObjectTypeDef, CatalogOverlay, CatalogPropertyDef, CatalogRelationDef, CatalogSnapshot, RelationKind, ScalarType, } from './catalog.types';
 export { REQUIRED_SCOPES, REQUIRES_HUMAN, RequireHuman, RequireScopes, } from './catalog.route-auth';