@dudousxd/nestjs-catalog 0.12.0 → 0.14.0

package/dist/catalog.pipeline.d.ts

@@ -122,6 +122,211 @@ export interface CatalogConnector {
     lastRunAt?: string;
     lastRunStatus?: 'succeeded' | 'failed' | 'running';
 }
+/**
+ * What a load has to be true of before it is allowed to become the data
+ * everybody reads.
+ *
+ * Two failures live here, and they are the same failure seen from two ends: a
+ * load that is *fresh and wrong*. Every signal this catalog publishes about a
+ * type — `lastCommittedAt`, the age badge on the Model screen, a green run in
+ * the runs list — reports on whether a load HAPPENED. None of them reports on
+ * whether what it loaded resembles the dataset it replaced, and a snapshot
+ * commit is atomic, so the moment a wrong load commits it is indistinguishable
+ * from a right one until somebody counts rows by hand.
+ *
+ * - **Deletes.** An incremental connector asks its source for what changed
+ *   since a watermark. A row physically removed from the source never changes
+ *   again, so it is never returned again, so `carryForward` copies it into
+ *   every subsequent snapshot forever. The catalog does not go wrong at any
+ *   point; it simply never finds out. See {@link DeleteReconciliation}.
+ * - **Collapse.** A source-side filter change, a broken `WHERE`, a partial
+ *   outage: the connector returns 12 rows where it returned 40,000, the
+ *   snapshot commits, and the freshness signals all say healthy — correctly,
+ *   because it IS fresh. See {@link RowCountBound}.
+ *
+ * **Why a policy object and not a column on the connector.** Both facts are
+ * statements about a *type*, not about the reader of a source. "It is
+ * acceptable that `Employee` accumulates rows deleted upstream" and "`Employee`
+ * must never lose half its rows in one load" stay true whether the rows arrive
+ * from a connector, from a workflow sink, or from an application POSTing to the
+ * publish API — and all three of those paths end at the same two methods on
+ * `PublishService`, which is where these are enforced. A per-connector field
+ * would have covered one of the three and would have had to be checked in three
+ * places to cover the rest.
+ *
+ * The second reason is who should be able to change it. Accepting that a
+ * dataset silently accumulates deleted rows is not a checkbox decision; it is
+ * the kind of thing that should appear in a diff with a reason attached, which
+ * is why {@link DeleteReconciliation} makes the reason a required field.
+ */
+export interface CatalogLoadExpectations {
+    /** Applied to every type that has no entry of its own. */
+    default?: LoadExpectation;
+    /**
+     * Keyed by object type name. Merged OVER {@link default} field by field, so a
+     * host can set one house-wide row-count bound and still say something about
+     * deletes for the three types that are loaded incrementally.
+     */
+    byType?: Record<string, LoadExpectation>;
+}
+export interface LoadExpectation {
+    /**
+     * How deletions at the source reach this type. **Absent means the load is
+     * refused**, which is the whole mechanism — see {@link
+     * refuseUndeclaredDeletes}.
+     */
+    deletes?: DeleteReconciliation;
+    /**
+     * How far one load may move this type's row count. Merged over
+     * {@link DEFAULT_ROW_COUNT_BOUND}, so a host that only wants to raise
+     * `maxShrink` writes exactly that one field.
+     */
+    rowCount?: Partial<RowCountBound>;
+}
+/**
+ * How a type that is loaded incrementally learns about rows that were deleted.
+ *
+ * Three answers, and the honest thing to say about them up front is that only
+ * one is *policed*. What this file enforces is that somebody chose one and
+ * wrote down why — because the state being prevented is nobody having thought
+ * about it at all, and that state is invisible by construction.
+ *
+ * The fourth answer, tombstones off a change feed, is the correct one and is
+ * deliberately not here. It needs the source to publish a delete stream, the
+ * catalog to hold a delete log per type, and the merge to apply it — which is
+ * a larger machine than the problem justifies today, and adding a strategy name
+ * that nothing implements would be exactly the dropdown-with-a-lie this
+ * codebase refuses everywhere else.
+ */
+export type DeleteReconciliation = 
+/**
+ * Nothing reconciles them, and that is a decision somebody made.
+ *
+ * The legitimate cases are real and common: an append-only ledger where rows
+ * are never removed, a source that only ever soft-retires records by changing
+ * a status the transform can see, or a dataset where a handful of stale rows
+ * is genuinely cheaper than a nightly full read. What is not legitimate is
+ * arriving here by default, which is why {@link because} cannot be omitted.
+ */
+{
+    strategy: 'accepted';
+    because: string;
+}
+/**
+ * The source marks a deletion instead of performing one, and the watermark
+ * therefore sees it — a `deleted_at` that moves, a status column that flips —
+ * so the deleted row arrives as an ordinary change and the transform drops it
+ * or the type keeps it flagged.
+ *
+ * The strongest of the three, and the one that pushes a requirement onto a
+ * source that may refuse it. Not verifiable from here: the catalog cannot
+ * tell a source that soft-deletes from one that claims to, so this is a
+ * declaration like the one above. It is a separate value anyway because the
+ * two say completely different things to the next person who reads the
+ * config, and collapsing them would lose that.
+ */
+ | {
+    strategy: 'soft-deleted-at-source';
+    because: string;
+    column?: string;
+}
+/**
+ * Full reads reconcile, incremental reads fill the gaps between them.
+ *
+ * The interval is the trade-off, and it is stated in time rather than in runs
+ * because "reconciled daily" is what anybody actually means and because the
+ * only thing the catalog can count is the snapshots a store chooses to
+ * report, which is a window of unknown depth. {@link refuseStaleReconciliation}
+ * makes the interval real: once the newest full load of the type is older
+ * than `withinMs`, incremental loads of it stop committing.
+ */
+ | {
+    strategy: 'periodic-full-reload';
+    because: string;
+    withinMs: number;
+};
+/**
+ * How far a single load may move a type's row count before it is refused.
+ *
+ * **Asymmetric on purpose.** A type that doubles has usually had a good day —
+ * a backfill landed, a new base was onboarded, a source finished catching up.
+ * A type that loses 90% has almost never had a good day. Bounding both sides by
+ * the same number would mean picking a growth bound loose enough to be useless
+ * as a shrink bound, or a shrink bound tight enough to refuse every backfill.
+ *
+ * **Conditional on the store, and a host configuring this should know which
+ * condition.** {@link refuseRowCountDrift} is pure and decides on two numbers;
+ * somebody has to fetch them, and both come from members that are optional on
+ * the store interface. Without `currentSnapshot` there is no served baseline;
+ * without `listSnapshots`, or from a `listSnapshots` whose window does not
+ * reach the snapshot about to be committed, there is no count for the pending
+ * one. Either way the bound is not applied to that commit. That is the same
+ * permissive-rather-than-punishing stance {@link CARRIED_FROM_LABEL} takes for
+ * the same reason — an adapter that records less than the bundled one is not
+ * the failure this file exists for — but it means a number written here is a
+ * bound the store has to be able to measure, not one it is guaranteed to have.
+ * `PublishService.assertRowCountIsPlausible` is where that is decided; a skip
+ * that is not said out loud there is a bound believed to be on and off, which
+ * is the one outcome neither this file nor that one may produce.
+ */
+export interface RowCountBound {
+    /**
+     * The largest fraction of the previously served snapshot a load may lose.
+     * `0.5` refuses a load that comes back with less than half of what is live.
+     */
+    maxShrink: number;
+    /**
+     * The ratio above which growth is refused — `10` refuses a load ten times the
+     * size of the previous one. **Absent means growth is never refused**, which is
+     * the default, because the failure this file exists for is collapse and a
+     * growth bound that fires on a legitimate backfill teaches people to raise
+     * every bound in this object until none of them do anything.
+     */
+    maxGrowth?: number;
+    /**
+     * Below this many rows in the previously served snapshot, no ratio applies.
+     *
+     * A percentage of a small number is noise. A four-row lookup table dropping to
+     * one is a 75% collapse and is also a Tuesday, and a bound that fires on it is
+     * a bound somebody switches off — taking the forty-thousand-row types with it.
+     */
+    minRows: number;
+}
+/**
+ * A per-type expectation as an operator set it, with who and when.
+ *
+ * The layer between a host's `byType` entry and its `default`. It exists because
+ * the control the docblocks above argue for was never "it must be in code" —
+ * it is that **somebody chose a strategy and wrote down why**, which needs
+ * attribution and visibility rather than compilation. A host object gives the
+ * reason a place to live and gives attribution to nobody: a `git blame` on a
+ * deployment's wiring names whoever last reformatted the file. So the reason
+ * arrives with the principal that set it and the instant they did, and the
+ * declaration requirement is unchanged — {@link refuseUndeclaredDeletes} asks
+ * the same question of a stored row as it does of a host one.
+ *
+ * The grain is still the type, and only the type. A connector, a workflow sink
+ * and an application POSTing to the publish API all end at the same two
+ * `PublishService` methods and all have the same delete problem, so a per-
+ * connector or per-workflow row would give one dataset several answers to one
+ * question — see {@link CatalogLoadExpectations}, which argues it at length and
+ * is unaffected by this layer existing.
+ *
+ * Both policy fields are optional, and a row may carry either, both or neither:
+ * precedence is resolved field by field, so an operator raising a shrink bound
+ * says nothing about deletes and does not have to.
+ */
+export interface StoredLoadExpectation {
+    typeName: string;
+    deletes?: DeleteReconciliation;
+    rowCount?: Partial<RowCountBound>;
+    /** Principal id of whoever set it. */
+    setBy: string;
+    /** Actor id when a person was behind the principal — the audit's real subject. */
+    setByActor?: string;
+    /** ISO 8601. */
+    setAt: string;
+}
 /**
  * TypeScript is Node's own type stripping, so it costs no compiler and no build
  * step — and types are erased, never checked. A transform with a wrong type
@@ -852,6 +1057,37 @@ export declare function supportsWorkflows(store: CatalogPipelineStore): store is
  */
 export declare function supportsTransformRevisions(store: CatalogPipelineStore): store is CatalogPipelineStore & Required<Pick<CatalogPipelineStore, 'listTransformRevisions'>>;
 export declare function supportsWorkflowStages(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogStageStore;
+/**
+ * A store that really does hold operator-set expectations, all four members
+ * present.
+ *
+ * Derived from {@link CatalogPipelineStore} rather than declared as a separate
+ * interface the way {@link CatalogWorkflowStore} is, and the difference is not
+ * stylistic: these four are optional members OF the pipeline store, so writing
+ * them out a second time here would be a copy that can drift from the one the
+ * signatures are read from. `CatalogWorkflowStore` predates that lesson and is
+ * mixed in through `Partial<>`, which reaches the same place from the other
+ * side.
+ */
+export type CatalogLoadExpectationStore = Required<Pick<CatalogPipelineStore, 'listLoadExpectations' | 'getLoadExpectation' | 'saveLoadExpectation' | 'clearLoadExpectation'>>;
+/**
+ * Whether an operator can set a load expectation on this deployment at all.
+ *
+ * The methods rather than a flag, the same argument as {@link supportsWorkflows}
+ * — and all four of them by name rather than one standing in for the rest, for
+ * that function's other reason: the write path and the read path are used at
+ * different moments, so a store with the getter and not the setter would narrow
+ * cleanly here and fail on the save, after the screen had already offered an
+ * editor.
+ *
+ * A store that has none of them is not broken and is not second-class. It
+ * behaves exactly as every store did before this existed: the host's
+ * `CATALOG_LOAD_EXPECTATIONS` object is the only layer, which is a complete and
+ * supported answer. What this probe buys is that the console can say "this
+ * deployment's store cannot hold operator-set expectations" instead of offering
+ * an editor whose save has nowhere to go.
+ */
+export declare function supportsLoadExpectations(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogLoadExpectationStore;
 export interface CatalogPipelineStore extends Partial<CatalogWorkflowStore>, Partial<CatalogStageStore> {
     listConnectors(): Promise<CatalogConnector[]>;
     getConnector(id: string): Promise<CatalogConnector | undefined>;
@@ -905,6 +1141,53 @@ export interface CatalogPipelineStore extends Partial<CatalogWorkflowStore>, Par
      * that bound costs.
      */
     listTransformRevisions?(id: string): Promise<CatalogRevision[]>;
+    /**
+     * Per-type load expectations as an operator set them.
+     *
+     * **Optional**, and here more deliberately than anywhere else in this
+     * interface. `@dudousxd/nestjs-catalog-store-mikro-orm` is not the only
+     * implementation — a host may have written its own against an earlier shape of
+     * this file — and every one of them satisfies `CatalogPipelineStore` today.
+     * Widening it with four required members would turn all of them into compile
+     * errors for a feature that is purely additive, and, worse, would do it
+     * *silently* to the ones checked structurally: `isPipelineStore` and the
+     * `supports*` probes narrow on methods, so a store that no longer satisfies
+     * the interface is discovered by a caller, at run time, rather than by a build.
+     * {@link supportsLoadExpectations} is how a caller asks, and a store that
+     * implements none of these behaves exactly as it does today — the host's
+     * `CATALOG_LOAD_EXPECTATIONS` object is then the whole policy.
+     *
+     * These hold rows; they do not resolve them. Precedence — a host's `byType`
+     * entry over a stored row over the host's `default`, field by field — is the
+     * pipeline package's business, beside the enforcement functions that consume
+     * it, and it stays pure and synchronous. A store that resolved would be a
+     * second place the precedence is decided, which for a policy whose whole point
+     * is "somebody decided this" is the one duplication that cannot be tolerated.
+     */
+    listLoadExpectations?(): Promise<StoredLoadExpectation[]>;
+    getLoadExpectation?(typeName: string): Promise<StoredLoadExpectation | undefined>;
+    /**
+     * Upsert, keyed by type name, recording the principal and the instant.
+     *
+     * `setBy` and `setByActor` are arguments rather than fields on the
+     * `expectation` for the reason `startRun` records attribution the way it does:
+     * a caller cannot claim them. `setAt` is not an input at all — a stored
+     * timestamp a client could choose is not an audit record.
+     *
+     * `setByActor` is the person behind the principal when there was one. The
+     * write route requires a human, so in practice there always is; it is
+     * separate from `setBy` because a principal is a key and an actor is a
+     * subject, and the trail needs the second to answer "who decided this".
+     */
+    saveLoadExpectation?(typeName: string, expectation: Pick<StoredLoadExpectation, 'deletes' | 'rowCount'>, setBy: string, setByActor?: string): Promise<StoredLoadExpectation>;
+    /**
+     * Drop the stored row for a type. The host's layer is untouched, so a type the
+     * deployment declared in code keeps that declaration.
+     *
+     * `false` means there was nothing stored, which is a fact a caller may report
+     * and never an error.
+     */
+    clearLoadExpectation?(typeName: string): Promise<boolean>;
     startRun(input: {
         connectorId: string;
         snapshotId: string;

package/dist/catalog.pipeline.js

@@ -23,6 +23,7 @@ exports.isWorkflowEdge = isWorkflowEdge;
 exports.supportsWorkflows = supportsWorkflows;
 exports.supportsTransformRevisions = supportsTransformRevisions;
 exports.supportsWorkflowStages = supportsWorkflowStages;
+exports.supportsLoadExpectations = supportsLoadExpectations;
 exports.isPipelineStore = isPipelineStore;
 /**
  * Where a connector pulls from.
@@ -729,6 +730,29 @@ function supportsTransformRevisions(store) {
 function supportsWorkflowStages(store) {
     return typeof store.writeStage === 'function' && typeof store.readStage === 'function';
 }
+/**
+ * Whether an operator can set a load expectation on this deployment at all.
+ *
+ * The methods rather than a flag, the same argument as {@link supportsWorkflows}
+ * — and all four of them by name rather than one standing in for the rest, for
+ * that function's other reason: the write path and the read path are used at
+ * different moments, so a store with the getter and not the setter would narrow
+ * cleanly here and fail on the save, after the screen had already offered an
+ * editor.
+ *
+ * A store that has none of them is not broken and is not second-class. It
+ * behaves exactly as every store did before this existed: the host's
+ * `CATALOG_LOAD_EXPECTATIONS` object is the only layer, which is a complete and
+ * supported answer. What this probe buys is that the console can say "this
+ * deployment's store cannot hold operator-set expectations" instead of offering
+ * an editor whose save has nowhere to go.
+ */
+function supportsLoadExpectations(store) {
+    return (typeof store.listLoadExpectations === 'function' &&
+        typeof store.getLoadExpectation === 'function' &&
+        typeof store.saveLoadExpectation === 'function' &&
+        typeof store.clearLoadExpectation === 'function');
+}
 exports.CATALOG_PIPELINE_STORE = Symbol('CATALOG_PIPELINE_STORE');
 function isPipelineStore(store) {
     return (typeof store === 'object' &&

package/dist/catalog.service.d.ts

@@ -63,6 +63,21 @@ export declare class CatalogService {
     readObjects(typeName: string, query: CatalogObjectQuery & {
         snapshot?: string;
     }): Promise<CatalogObjectPage>;
+    /** What the mounted store can push into a read predicate. Empty when it cannot. */
+    private filterOperators;
+    /**
+     * Every filter, or a refusal naming all of them at once.
+     *
+     * One message listing every problem rather than the first: somebody who built
+     * four filters and got two of them wrong should learn that in one round trip.
+     *
+     * The store is asked whether it can honour the operators before the read runs,
+     * which is what stops a store that does not filter from answering with an
+     * unfiltered page. That refusal is worth more than it costs — a screen only
+     * offers what `filterOperators` reported, so a caller reaching this branch is
+     * one that built the request itself.
+     */
+    private resolveFilters;
     /** Empty when the store keeps no history. */
     listSnapshots(typeName: string): Promise<SnapshotRef[]>;
     /** What the mounted store can do — the screens branch on this. */

package/dist/catalog.service.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CatalogService = void 0;
 const common_1 = require("@nestjs/common");
 const catalog_events_1 = require("./catalog.events");
+const catalog_filters_1 = require("./catalog.filters");
 const catalog_options_1 = require("./catalog.options");
 const catalog_query_1 = require("./catalog.query");
 const catalog_query_cache_1 = require("./catalog.query-cache");
@@ -130,14 +131,24 @@ let CatalogService = class CatalogService {
         // Sort is validated here rather than in the store: an unrecognised column
         // must never reach a query builder, whatever the engine.
         const sort = columns.some((c) => c.name === query.sort) ? query.sort : undefined;
-        const { rows, total } = await this.store.read(type, fields, {
+        // Filters, against the same `columns` a sort is checked against and for the
+        // same reason — with one difference in what a failure means. An unrecognised
+        // sort falls back to the primary key, because the rows are the same rows in a
+        // different order. An unrecognised filter cannot fall back to anything: the
+        // read would come back holding rows the caller asked to exclude, and neither
+        // the caller nor the screen has any way to tell.
+        const filters = this.resolveFilters(columns, query.filters ?? []);
+        const result = await this.store.read(type, fields, {
             page,
             size,
             search: query.search,
             sort,
             dir: query.dir === 'desc' ? 'desc' : 'asc',
             snapshot: query.snapshot,
+            ...(filters.length > 0 ? { filters } : {}),
         });
+        const { rows, total } = result;
+        const storeOperators = this.filterOperators();
         return {
             type: type.name,
             page,
@@ -150,10 +161,52 @@ let CatalogService = class CatalogService {
                 type: c.type,
                 classification: c.classification,
                 unit: c.unit,
+                columnName: c.columnName,
+                // What this deployment will actually accept for this column: the rule
+                // derived from the column, narrowed by what the mounted store can do.
+                // Sent per column so a console needs no second request and no table of
+                // its own — see `catalog.filters.ts` on why a hand-kept list is the
+                // failure mode being avoided.
+                filterOperators: (0, catalog_filters_1.offeredFilterOperators)(c, storeOperators),
             })),
             rows,
+            ...(result.snapshot ? { snapshot: result.snapshot } : {}),
         };
     }
+    /** What the mounted store can push into a read predicate. Empty when it cannot. */
+    filterOperators() {
+        return (0, catalog_store_1.supportsObjectFilters)(this.store) ? this.store.objectFilterOperators : [];
+    }
+    /**
+     * Every filter, or a refusal naming all of them at once.
+     *
+     * One message listing every problem rather than the first: somebody who built
+     * four filters and got two of them wrong should learn that in one round trip.
+     *
+     * The store is asked whether it can honour the operators before the read runs,
+     * which is what stops a store that does not filter from answering with an
+     * unfiltered page. That refusal is worth more than it costs — a screen only
+     * offers what `filterOperators` reported, so a caller reaching this branch is
+     * one that built the request itself.
+     */
+    resolveFilters(columns, raw) {
+        if (raw.length === 0)
+            return [];
+        const { filters, problems } = (0, catalog_filters_1.resolveObjectFilters)(columns, raw);
+        const supported = this.filterOperators();
+        const unsupported = filters
+            .map((filter) => filter.op)
+            .filter((op) => !supported.some((available) => available === op));
+        if (unsupported.length > 0) {
+            throw new common_1.BadRequestException(supported.length === 0
+                ? "This catalog's store does not filter object reads, so it can only be paged, searched and sorted."
+                : `This catalog's store cannot filter with ${[...new Set(unsupported)].join(', ')}. It applies ${supported.join(', ')}.`);
+        }
+        if (problems.length > 0) {
+            throw new common_1.BadRequestException(problems.join(' '));
+        }
+        return filters;
+    }
     /** Empty when the store keeps no history. */
     async listSnapshots(typeName) {
         const type = this.registry.getType(typeName);

package/dist/catalog.store.d.ts

@@ -1,4 +1,5 @@
 import { BadRequestException } from '@nestjs/common';
+import type { CatalogFilterOperator, CatalogResolvedFilter } from './catalog.filters';
 import type { CatalogObjectQuery, CatalogObjectTypeDef } from './catalog.types';
 /**
  * Where the objects actually live.
@@ -149,14 +150,74 @@ export interface CatalogStoreCapabilities {
  * into a boot failure.
  */
 export declare function isCatalogStoreCapabilities(value: unknown): value is CatalogStoreCapabilities;
-export interface CatalogReadQuery extends CatalogObjectQuery {
+/**
+ * What a store is asked for, once the service has vetted it.
+ *
+ * `Omit<..., 'filters'>` and not a plain extension, and the omission is the
+ * point: `CatalogObjectQuery.filters` is the caller's raw
+ * `property:operator:value` text, and a store must never be handed one. What
+ * arrives here instead is {@link CatalogResolvedFilter}, whose property is the
+ * type's own definition — so the column a predicate is built from came off the
+ * type rather than off the request, and the type system says so rather than a
+ * comment. `sort` is a bare string only because every store already re-matches it
+ * against the type before using it; a filter carries more than a name, so
+ * resolving it once in the service is both cheaper and harder to get wrong.
+ */
+export interface CatalogReadQuery extends Omit<CatalogObjectQuery, 'filters'> {
     /** Read as of a specific snapshot. Ignored when `timeTravel` is false. */
     snapshot?: string;
+    /**
+     * Every one of these must be applied. A store that cannot apply one must not
+     * silently return the rows it would have returned anyway — declare the
+     * operators it can honour (see {@link CatalogFilteringReadStore}) and the
+     * service will refuse the read instead.
+     */
+    filters?: CatalogResolvedFilter[];
 }
 export interface CatalogReadResult {
     rows: Array<Record<string, unknown>>;
     total: number;
+    /**
+     * Which snapshot these rows came from, and whether it is the one being served.
+     *
+     * Answered by the store because the store is what resolved it: a read that was
+     * given no snapshot falls back to the pointer, so only the store knows which id
+     * the rows actually carry. Reporting it costs nothing — every store that keeps
+     * history has already read both values by the time it builds the query — and it
+     * is what lets a screen say "this is not the current load" on the strength of
+     * what was read rather than of what it thinks it asked for.
+     *
+     * Absent from a store that keeps no history, which is the honest answer there:
+     * the rows are the current state and there is no other state to be reading.
+     */
+    snapshot?: {
+        id: string;
+        current: boolean;
+    };
 }
+/**
+ * A store that applies {@link CatalogReadQuery.filters}.
+ *
+ * Declared, never assumed, and the reason is the same one the capability object
+ * one file up gives for every field on it: a store that ignores a filter answers
+ * with more rows than were asked for, and there is nothing about that answer to
+ * distinguish it from a filter that genuinely matched everything. So a store says
+ * which operators it can push into its predicate, the service offers exactly
+ * those to the screen, and a filter naming anything else is refused rather than
+ * quietly dropped.
+ *
+ * A guard rather than a field on `CatalogStoreCapabilities`, deliberately: the
+ * capability object is intersected by the fan-out through an exhaustiveness check
+ * that fails to compile when a field is added and not composed, and this is not a
+ * property that composes the way those do — a fan-out reads through its primary,
+ * so what its primary can filter is what it can filter. Asking the object it
+ * holds is the check that stays true when that changes.
+ */
+export interface CatalogFilteringReadStore extends CatalogReadStore {
+    /** Which operators this store can apply. A subset of `CATALOG_FILTER_OPERATORS`. */
+    readonly objectFilterOperators: readonly CatalogFilterOperator[];
+}
+export declare function supportsObjectFilters(store: unknown): store is CatalogFilteringReadStore;
 /** The minimum a store must do: return rows of a catalogued type. */
 export interface CatalogReadStore {
     readonly capabilities: CatalogStoreCapabilities;
@@ -345,6 +406,31 @@ export interface CatalogMergeStore extends CatalogWriteStore {
 export declare const CATALOG_RESERVED_COLUMNS: readonly ["_snapshot_id", "_principal_id", "_loaded_at", "_batch", "_row"];
 export type CatalogReservedColumn = (typeof CATALOG_RESERVED_COLUMNS)[number];
 export declare function isReservedColumn(column: string): boolean;
+/**
+ * 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.
+ */
+export declare class UnsafeIdentifierError extends Error {
+    constructor(value: string);
+}
+/** Whether a name can be written into SQL as it stands. */
+export declare function isSafeIdentifier(value: string): boolean;
+/**
+ * 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.
+ */
+export declare function assertSafeIdentifier(value: string): void;
 /** One property, and the column it cannot have. */
 export interface CatalogColumnCollision {
     /** `reserved` — it lands on a store column. `shared` — two properties collide. */

package/dist/catalog.store.js

@@ -1,8 +1,11 @@
 "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.supportsObjectFilters = supportsObjectFilters;
 exports.isReservedColumn = isReservedColumn;
+exports.isSafeIdentifier = isSafeIdentifier;
+exports.assertSafeIdentifier = assertSafeIdentifier;
 exports.findColumnCollisions = findColumnCollisions;
 exports.assertNoColumnCollisions = assertNoColumnCollisions;
 exports.isWriteStore = isWriteStore;
@@ -47,6 +50,11 @@ function isCatalogStoreCapabilities(value) {
     }
     return true;
 }
+function supportsObjectFilters(store) {
+    return (typeof store === 'object' &&
+        store !== null &&
+        Array.isArray(Reflect.get(store, 'objectFilterOperators')));
+}
 /**
  * The columns a snapshot-emulating store adds to every object table.
  *
@@ -72,6 +80,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.
  *