@dudousxd/nestjs-catalog 0.23.0 → 0.25.0

package/dist/catalog.environment.d.ts

@@ -24,7 +24,7 @@
  * its own durable keyspace ({@link durableKeyspaceFor}), for the reason spelled
  * out there.
  */
-import type { ConnectorKind, TransformLanguage, WorkflowEdge, WorkflowNode } from './catalog.pipeline';
+import type { ConnectorKind, TransformLanguage, TransformMode, WorkflowEdge, WorkflowNode } from './catalog.pipeline';
 /**
  * Where a request declares its environment.
  *
@@ -75,6 +75,58 @@ export interface CatalogEnvironment {
      * `obj_<type>`) and carry no environment in them, so two environments in one
      * database would collide on every table. Separate databases make the
      * collision impossible and make MySQL's own `GRANT` the enforcement point.
+     *
+     * ## PostgreSQL keeps this exactly, and there the choice is a real one
+     *
+     * The sentence above leans on MySQL not distinguishing the two words. Postgres
+     * does distinguish them, and in a way that looks like an invitation: one
+     * connection reaches many schemas, which MySQL cannot do, so each environment
+     * could be a schema in one database behind one connection pool. That is
+     * cheaper — one pool instead of N — and it is refused.
+     *
+     * **The property that has to survive is the one this file is built around:
+     * there is no ambient default, and a cross-environment read is impossible
+     * because the database makes it so rather than because the application was
+     * careful.** Schema-per-environment cannot keep it, by either of the two
+     * routes available.
+     *
+     * *Route one, `search_path`.* Isolation then rests on a session variable on a
+     * pooled connection — and that is not a hypothetical hazard here, it is one
+     * this codebase has already measured and written up. `runReadOnlyQuery` in the
+     * MikroORM store deliberately passes its statement timeout as a per-statement
+     * hint rather than `SET SESSION`, because the session form was observed riding
+     * the pooled connection into an unrelated request: "after one query-console
+     * request, a *different* `em.fork()` read `@@SESSION.MAX_EXECUTION_TIME` back
+     * as the value set here". A leaked `MAX_EXECUTION_TIME` is a slow query. A
+     * leaked `search_path` is dev's request answered out of production's schema,
+     * returning entirely plausible rows, which is the failure
+     * {@link resolveEnvironment} exists to make impossible.
+     *
+     * *Route two, qualify every identifier.* Then isolation is a prefix that has to
+     * be present on every statement — which is the same class of thing as a
+     * `WHERE` clause, and this interface's own docblock says why that is refused:
+     * "there is no field here that a `WHERE` clause could be built out of, because
+     * a filter is precisely the sort of isolation that fails silently the one time
+     * somebody forgets it". A forgotten schema qualifier is a forgotten filter.
+     *
+     * And `GRANT` cannot rescue either route, which is the argument that actually
+     * settles it. One connection pool is one role; if that role can reach both
+     * schemas — which is what "one connection reaches many schemas" *means* — then
+     * `GRANT` is enforcing nothing between them. Making it the enforcement point
+     * again requires a role per environment, a role per environment requires a
+     * connection per environment, and at that point the shared pool that motivated
+     * the whole idea is gone and separate databases cost nothing extra.
+     *
+     * **What it costs:** N connection pools on Postgres, the same as on MySQL, and
+     * no cross-environment SQL join. The second is a feature — data never moves
+     * between environments — and the first is the price of the guarantee.
+     *
+     * **What an operator has to know:** nothing new. The deployment story is the
+     * same on both engines, which is the main thing this choice buys: one
+     * `catalogDatabaseNameFor`, one `ensureDatabase`, one shape of `GRANT`, and no
+     * per-engine paragraph in a runbook. The genuine Postgres/MySQL differences
+     * live in the store's `dialect.ts` and are about column case and search, not
+     * about isolation.
      */
     databaseName: string;
     /**
@@ -337,6 +389,17 @@ export interface PromotableTransform {
     description?: string;
     language: TransformLanguage;
     code: string;
+    /**
+     * Whether the code is called once with the batch or once per record.
+     *
+     * Carried, and **resolved** rather than left absent, unlike most optional
+     * fields on this shape. The mode decides what the same text means, so a
+     * promotion that dropped it would run the identical transform under a
+     * different contract in production than in dev — the one failure a promotion
+     * exists to make impossible. Resolved because a plan is a description of what
+     * the apply will do, and "absent, and the target will decide" is not one.
+     */
+    mode: TransformMode;
     /** The source's version, carried for the record only — see {@link planPromotion}. */
     version: number;
 }

package/dist/catalog.environment.js

@@ -77,15 +77,43 @@ const ENVIRONMENT_ID_PATTERN = /^[a-z][a-z0-9_]{0,23}$/;
  * module refuses it as a tenant: "default" is the value that means "no
  * namespace at all", so an environment called `default` would derive the bare
  * keyspace and quietly share a results queue with every other engine on the
- * Redis. The rest are MySQL's own schemas, which an environment must never be
- * pointed at.
+ * Redis.
+ *
+ * The rest are databases the *engine* owns, and an environment must never be
+ * pointed at one — an environment id becomes a database name, so `mysql` or
+ * `postgres` here means this package running `CREATE TABLE catalog_object_type`
+ * inside the server's own maintenance database.
+ *
+ * **Both engines' lists, on both engines, deliberately.** The alternative is a
+ * refusal that depends on which driver happens to be mounted, and that is the
+ * shape that bites during a migration: an environment named `postgres` is
+ * perfectly legal on MySQL today and becomes a live incident on the day somebody
+ * moves the deployment, at which point renaming an environment means renaming
+ * its database, its MikroORM context and its Redis keyspace. Refusing the union
+ * costs a deployment nothing — nobody wants an environment called
+ * `information_schema` — and keeps the answer the same everywhere.
+ *
+ * `template0` and `template1` are Postgres's own, and are the two most likely to
+ * be typed by accident by somebody who has just read a `createdb` man page.
  */
 const RESERVED_ENVIRONMENT_IDS = [
     'default',
+    // MySQL's.
     'information_schema',
     'mysql',
     'performance_schema',
     'sys',
+    // PostgreSQL's. `postgres` is the maintenance database every cluster ships
+    // with and the one a client connects to when it has nowhere else to go.
+    'postgres',
+    'template0',
+    'template1',
+    // Not a database but a schema, and reserved because a Postgres deployment
+    // that ever did put environments in schemas would collide with the default
+    // one — see the note on `databaseName` for why this package does not.
+    'public',
+    'pg_catalog',
+    'pg_toast',
 ];
 function isEnvironmentId(value) {
     return (typeof value === 'string' &&
@@ -407,7 +435,18 @@ function planTransforms(source, target, selected) {
         if (!selected('transform', transform.id))
             continue;
         const existing = targetTransforms.get(transform.id);
-        const fields = diffFields(existing, transform, ['name', 'description', 'language', 'code']);
+        // `mode` is compared, and forgetting it would be the quiet failure this
+        // whole field exists to prevent: a transform switched from batch to
+        // per-record with its code untouched is a real change to what it computes,
+        // and a plan that reported "nothing to release" would leave production
+        // running the other contract.
+        const fields = diffFields(existing, transform, [
+            'name',
+            'description',
+            'language',
+            'code',
+            'mode',
+        ]);
         changes.push({
             kind: 'transform',
             id: transform.id,

package/dist/catalog.pipeline.d.ts

@@ -425,6 +425,65 @@ export declare const TRANSFORM_LANGUAGES: readonly ["javascript", "typescript",
 export type TransformLanguage = (typeof TRANSFORM_LANGUAGES)[number];
 /** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
 export declare function isTransformLanguage(value: unknown): value is TransformLanguage;
+/**
+ * Whether a transform is a function over the whole batch or over one record.
+ *
+ * ## Why this is declared and never inferred
+ *
+ * The two are not interchangeable and the difference is invisible in the code.
+ * `records.map(...)` and a body that returns one object read almost identically,
+ * and a detector that guessed from destructuring — `{ records }` versus
+ * `{ record }` — would be reading a *parameter name*, which is the author's to
+ * choose and which minification, a rename, or a rest parameter changes without
+ * changing what the function computes. Guess wrong towards `record` and an
+ * aggregation is called 102,520 times and returns 102,520 partial answers, none
+ * of which fails; guess wrong towards `batch` and a per-record function is handed
+ * an array and reads `undefined` off every property. Both commit. Neither errors.
+ * So the mode is a field somebody set, and the cost of setting it is one control
+ * in the editor.
+ *
+ * ## Why a closed list rather than `streaming?: boolean`
+ *
+ * The identical argument {@link WORKFLOW_CALL_MODES} makes one level up. A flag
+ * beside a future third calling convention — a windowed transform, a keyed one —
+ * is two optional booleans whose combinations nobody defined, and each reader
+ * invents its own rule for which wins. A closed list with an exhaustiveness guard
+ * ({@link unreachableTransformMode}) makes a third convention a compile error
+ * naming the files that have to answer for it: the harness that generates the
+ * call, the runner that chooses a transport, and the two runners that consume
+ * the result.
+ *
+ * ## What the default has to be, and why it is not a choice
+ *
+ * Absent means {@link CatalogTransform.mode} was never set, which is every
+ * transform stored before this field existed, and every one of them is a function
+ * over the whole batch — the harness handed it `records` and there was no other
+ * shape to write. Reading absence as anything else would silently change what a
+ * deployment's existing loads compute. Read it through {@link transformMode}
+ * rather than defaulting it a second time.
+ */
+export declare const TRANSFORM_MODES: readonly ["batch", "record"];
+export type TransformMode = (typeof TRANSFORM_MODES)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isTransformMode(value: unknown): value is TransformMode;
+/**
+ * {@link unreachableCallMode}, for transforms, and for the identical reason.
+ *
+ * Every branch over {@link TransformMode} ends here, so a third calling
+ * convention added to the list without a harness to generate it, a transport to
+ * carry it and a consumer to read its output is a type error naming the file. It
+ * throws as well, because a mode arrives as JSON out of a column and a build
+ * older than the data is a thing that happens.
+ */
+export declare function unreachableTransformMode(mode: never, where: string): never;
+/**
+ * The mode this transform runs in, with the default applied once.
+ *
+ * Absent means `'batch'` — see {@link TRANSFORM_MODES}. One function so that the
+ * store, the runner, the two consumers, the editor and the try pane cannot each
+ * carry their own `?? 'batch'` and have one of them drift.
+ */
+export declare function transformMode(transform: Pick<CatalogTransform, 'mode'>): TransformMode;
 /**
  * User code that maps a source record to a row.
  *
@@ -481,11 +540,40 @@ export interface CatalogTransform {
      * a new field costs one generated line rather than an edit to stored code.
      */
     code: string;
+    /**
+     * Whether {@link code} is called once with the batch or once per record.
+     *
+     * Absent means `'batch'`, which is what every transform stored before this
+     * field existed is. See {@link TRANSFORM_MODES} for why it is declared rather
+     * than inferred, and read it through {@link transformMode}.
+     *
+     * A `'record'` transform is constrained in two ways the mode alone does not
+     * say, and both are refused rather than discovered at run time — see
+     * {@link recordModeRefusal}: it must be a **module**, because a bare body has
+     * `records` in scope by the harness's own construction, and it cannot be
+     * **Python**, because that harness writes the `def` and has no second one yet.
+     */
+    mode?: TransformMode;
     version: number;
     createdBy: string;
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Why this transform cannot run in the mode it declares, if it cannot.
+ *
+ * Two combinations are representable and neither can work, so both are refused
+ * at the point somebody presses save rather than at three in the morning when a
+ * schedule fires. `undefined` means there is nothing wrong.
+ *
+ * Asked in both places on purpose. The controller asks so the author is told
+ * while they are still looking at the code; the runner asks because a row can
+ * reach it that no controller in this build ever validated — promoted from
+ * another environment, restored from a backup, written by an older version — and
+ * the failure a runner must never have is the silent one where a per-record
+ * module is handed an array and quietly reads `undefined` off every property.
+ */
+export declare function recordModeRefusal(transform: Pick<CatalogTransform, 'language' | 'code' | 'mode'>): string | undefined;
 /**
  * The single argument a module-shaped transform is called with.
  *
@@ -557,6 +645,77 @@ export interface CatalogTransformInput<TRecord = Record<string, unknown>> {
  * ```
  */
 export type CatalogTransformFunction<TRecord = Record<string, unknown>> = (input: CatalogTransformInput<TRecord>) => Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>;
+/**
+ * The single argument a `'record'`-mode transform is called with, once per
+ * record.
+ *
+ * One object, for the reason {@link CatalogTransformInput} gives and not a
+ * second time: a field can be added later without redefining what any signature
+ * already written means.
+ *
+ * ## `record` rather than `records`, deliberately one letter apart
+ *
+ * Which is a real risk and was weighed against the alternatives. A name like
+ * `row` or `item` would be further from its sibling and would be *wrong*: what
+ * arrives is a record exactly as the source produced it, and a row is what the
+ * transform returns — the two words already mean different things everywhere
+ * else in this package, and borrowing one of them here to reduce a typo would
+ * make the vocabulary lie.
+ *
+ * The typo it invites is also the one mistake in this area that cannot go quiet.
+ * `{ records }` in a per-record transform destructures `undefined`, and the first
+ * thing anybody does with it — `.map`, `.length`, `.filter` — throws on the very
+ * first record, with a stack frame in the author's own file. The dangerous
+ * direction is the other one, and that is exactly what {@link TRANSFORM_MODES}
+ * refuses to guess about.
+ *
+ * ## What is not on it
+ *
+ * No index, no total, no `isFirst`. Each of those is a way to write a transform
+ * whose answer depends on where a record fell in the stream, which is the
+ * property this mode exists to *not* have — a record's row must be a function of
+ * that record. `context.rowCount` is a count of what reached the node and is
+ * already there for anything that legitimately needs the size of the load.
+ */
+export interface CatalogRecordTransformInput<TRecord = Record<string, unknown>> {
+    /** One record, exactly as the source produced it. */
+    record: TRecord;
+    /** The run, the node, the counts, and the admitted environment variables. */
+    context: CatalogCodeContext;
+}
+/**
+ * The function a `'record'`-mode transform exports.
+ *
+ * **For the editor and nothing else**, exactly as {@link CatalogTransformFunction}
+ * is: TypeScript transforms run through Node's own type *stripping*, so the
+ * annotations are erased on the way in and a wrong one is a squiggle rather than
+ * a failed run.
+ *
+ * The return type is the whole contract of the mode and it is deliberately four
+ * things at once:
+ *
+ * - **an object** — one row, the ordinary case;
+ * - **an array** — several rows, so one record can fan out;
+ * - **an empty array** — no rows, so a record can be dropped;
+ * - **`null` or `undefined`** — no rows either, because that is what a function
+ *   with a bare `return` or a missed branch produces and reading it as anything
+ *   else would invent a row nobody wrote.
+ *
+ * Map, filter and flatMap under one rule, and no ambiguity between the first two
+ * cases: an array is never a row, because a row is a plain object everywhere in
+ * this package and the runners have always dropped anything else.
+ *
+ * ```ts
+ * import type { CatalogRecordTransformFunction } from '@dudousxd/nestjs-catalog/client';
+ *
+ * const transform: CatalogRecordTransformFunction<{ 'Mgmt Cd': string }> = ({ record }) => ({
+ *   mgmtCd: record['Mgmt Cd'],
+ * });
+ *
+ * export default transform;
+ * ```
+ */
+export type CatalogRecordTransformFunction<TRecord = Record<string, unknown>> = (input: CatalogRecordTransformInput<TRecord>) => Record<string, unknown> | Array<Record<string, unknown>> | null | undefined | Promise<Record<string, unknown> | Array<Record<string, unknown>> | null | undefined>;
 export interface TransformResult {
     rows: Array<Record<string, unknown>>;
     /**
@@ -595,11 +754,87 @@ export interface TransformResult {
  * people who are not already trusted with the database needs a container or a
  * sandboxed runtime, and this interface is where that gets plugged in.
  */
+/**
+ * What a per-record run produced, asked **only after {@link TransformStream.rows}
+ * is exhausted**.
+ *
+ * The stream equivalent of {@link TransformResult}, and it is a separate shape
+ * rather than the same one because the fields genuinely differ in *when they are
+ * knowable*. `rows` is not a value here — the whole point is that nothing holds
+ * them — so what is left is the counts and the log, and neither is final until
+ * the last record has gone past. `recordsIn` is new and is the one number a
+ * batch call never needed: a caller that streamed its source has no `.length` to
+ * report as `fetched`.
+ */
+export interface TransformStreamSummary {
+    /** How many records the runner fed the code. */
+    recordsIn: number;
+    /** How many rows came back, over every record. */
+    rowsOut: number;
+    /** {@link TransformResult.logs}, bounded by the runner in exactly the same way. */
+    logs: string[];
+    elapsedMs: number;
+}
+/**
+ * A per-record run in progress: the rows as they arrive, and the counts once
+ * they have.
+ *
+ * The same two-part shape `StreamedFetchResult` uses in the pipeline package —
+ * an iterable plus a function asked afterwards — and copied from it on purpose
+ * rather than invented. The reason it gives is the reason here: a stream is not
+ * complete until it has been drained, so anything computed *over* it is not yet
+ * known when the call returns, and a field would hand a caller a number that
+ * stops short of the rows they have already written.
+ *
+ * {@link summary} before {@link rows} is exhausted is a programming error and
+ * the bundled runner throws rather than answering with a running total, because
+ * a running total is exactly what somebody would then record as `fetched`.
+ */
+export interface TransformStream {
+    /**
+     * The rows, in record order, in the order the code emitted them.
+     *
+     * Pulled, not pushed: the next record is not fed to the code until the row
+     * before it has been taken, so a consumer that writes to a database
+     * back-pressures all the way to the source. That is the property the mode
+     * exists for and it is the caller's to keep — a consumer that collects this
+     * into an array has re-created the whole-batch memory profile with extra
+     * steps.
+     *
+     * Throws where the code threw, naming the record. See the runner.
+     */
+    rows: AsyncIterable<Record<string, unknown>>;
+    /** The counts and the log. Call only after {@link rows} is exhausted. */
+    summary(): TransformStreamSummary;
+}
 export interface TransformRunner {
     run(transform: Pick<CatalogTransform, 'language' | 'code'>, records: unknown[], options?: {
         timeoutMs?: number;
         context?: CatalogCodeContext;
     }): Promise<TransformResult>;
+    /**
+     * Run a `'record'`-mode transform over a stream of records, streaming the rows
+     * back.
+     *
+     * **Optional**, mixed in for the reason every optional member of
+     * {@link CatalogPipelineStore} is: a runner written against the previous shape
+     * of this interface still satisfies it, and a purely additive capability must
+     * not turn that into a compile error. {@link supportsTransformStreaming} is how
+     * a caller asks; a deployment whose runner cannot stream runs a per-record
+     * transform through {@link run} against a buffered batch instead, which is
+     * slower and holds more but computes the identical rows.
+     *
+     * Not a widening of {@link run}. The two differ in what the caller must hand
+     * over (an array against an iterable), in what comes back (rows against a
+     * stream of them), in when the counts are knowable, and in what the timeout
+     * measures — see the bundled runner, where a stream is bounded by a stall
+     * rather than by total wall clock. One method doing both would have four
+     * optional fields and a reader could not tell which combination was legal.
+     */
+    runStream?(transform: Pick<CatalogTransform, 'language' | 'code' | 'mode'>, records: AsyncIterable<unknown>, options?: {
+        timeoutMs?: number;
+        context?: CatalogCodeContext;
+    }): Promise<TransformStream>;
     /** Languages this runner can actually execute in this environment. */
     available(): Promise<TransformLanguage[]>;
     /**
@@ -611,6 +846,16 @@ export interface TransformRunner {
      */
     pythonPackages?(): Promise<string[]>;
 }
+/**
+ * Whether this runner can stream a per-record transform.
+ *
+ * The method rather than a flag, exactly as {@link supportsTransformRevisions}
+ * argues one interface along: a flag is a claim and a method is the thing
+ * itself. A runner that answers `false` still runs `'record'` transforms — the
+ * consumers buffer and call {@link TransformRunner.run} — so this is a question
+ * about *how much is held*, never about whether the load works.
+ */
+export declare function supportsTransformStreaming(runner: TransformRunner): runner is TransformRunner & Required<Pick<TransformRunner, 'runStream'>>;
 export declare const TRANSFORM_RUNNER: unique symbol;
 /**
  * The number in {@link CatalogCodeContext.contract}.
@@ -3677,6 +3922,13 @@ export interface CatalogPipelineStore extends Partial<CatalogWorkflowStore>, Par
     saveTransform(input: Pick<CatalogTransform, 'name' | 'language' | 'code'> & {
         id?: string;
         description?: string;
+        /**
+         * Absent leaves the stored mode alone rather than resetting it to
+         * `'batch'`, which is what a caller written before this field existed
+         * means and the only reading under which such a caller cannot silently
+         * change what a transform computes. See {@link TRANSFORM_MODES}.
+         */
+        mode?: TransformMode;
     }, createdBy: string): Promise<CatalogTransform>;
     deleteTransform(id: string): Promise<boolean>;
     /**

package/dist/catalog.pipeline.js

@@ -9,11 +9,16 @@
  * systems each believing they decide when a load runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REDACTED_SECRET = exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_CALL_CONTRACT = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_BRANCH_LABELS = exports.NODE_KIND_IS_REUSABLE = exports.REUSABLE_NODE_KINDS = exports.WORKFLOW_RENAME_MAX_COLUMNS = exports.WORKFLOW_RENAME_UNNAMED = exports.WORKFLOW_FILTER_MAX_VALUES = exports.WORKFLOW_FILTER_MAX_DEPTH = exports.WORKFLOW_FILTER_COLUMN_PATTERN = exports.WORKFLOW_FILTER_OPERATORS = exports.WORKFLOW_FILTER_PREDICATE_KINDS = exports.WORKFLOW_PREDICATE_KINDS = exports.WORKFLOW_CALL_MODES = exports.WORKFLOW_ROW_GAP = exports.WORKFLOW_COLUMN_GAP = exports.WORKFLOW_NODE_HEIGHT = exports.WORKFLOW_NODE_WIDTH = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_SKIP_REASONS = exports.CODE_CONTEXT_CONTRACT = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.SOURCE_FORMATS = exports.CONNECTOR_KINDS = void 0;
+exports.REDACTED_SECRET = exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_CALL_CONTRACT = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_BRANCH_LABELS = exports.NODE_KIND_IS_REUSABLE = exports.REUSABLE_NODE_KINDS = exports.WORKFLOW_RENAME_MAX_COLUMNS = exports.WORKFLOW_RENAME_UNNAMED = exports.WORKFLOW_FILTER_MAX_VALUES = exports.WORKFLOW_FILTER_MAX_DEPTH = exports.WORKFLOW_FILTER_COLUMN_PATTERN = exports.WORKFLOW_FILTER_OPERATORS = exports.WORKFLOW_FILTER_PREDICATE_KINDS = exports.WORKFLOW_PREDICATE_KINDS = exports.WORKFLOW_CALL_MODES = exports.WORKFLOW_ROW_GAP = exports.WORKFLOW_COLUMN_GAP = exports.WORKFLOW_NODE_HEIGHT = exports.WORKFLOW_NODE_WIDTH = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_SKIP_REASONS = exports.CODE_CONTEXT_CONTRACT = exports.TRANSFORM_RUNNER = exports.TRANSFORM_MODES = exports.TRANSFORM_LANGUAGES = exports.SOURCE_FORMATS = exports.CONNECTOR_KINDS = void 0;
 exports.isConnectorKind = isConnectorKind;
 exports.isSourceFormat = isSourceFormat;
 exports.unreachableSourceFormat = unreachableSourceFormat;
 exports.isTransformLanguage = isTransformLanguage;
+exports.isTransformMode = isTransformMode;
+exports.unreachableTransformMode = unreachableTransformMode;
+exports.transformMode = transformMode;
+exports.recordModeRefusal = recordModeRefusal;
+exports.supportsTransformStreaming = supportsTransformStreaming;
 exports.isWorkflowSkipReason = isWorkflowSkipReason;
 exports.isWorkflowNodeKind = isWorkflowNodeKind;
 exports.unreachableNodeKind = unreachableNodeKind;
@@ -75,6 +80,11 @@ exports.isPipelineStore = isPipelineStore;
 // edge only ever points this way: `catalog.workspace.ts` knows nothing about
 // pipelines.
 const catalog_workspace_1 = require("./catalog.workspace");
+// The one rule that tells a module-shaped transform from a bare body, used here
+// to refuse a per-record transform written as a body. The edge only points this
+// way: `transform-shape.ts` imports nothing at all, so it can be read on its own
+// and cannot be dragged into a cycle.
+const transform_shape_1 = require("./transform-shape");
 /**
  * Where a connector pulls from.
  *
@@ -183,6 +193,128 @@ exports.TRANSFORM_LANGUAGES = ['javascript', 'typescript', 'python'];
 function isTransformLanguage(value) {
     return exports.TRANSFORM_LANGUAGES.some((language) => language === value);
 }
+/**
+ * Whether a transform is a function over the whole batch or over one record.
+ *
+ * ## Why this is declared and never inferred
+ *
+ * The two are not interchangeable and the difference is invisible in the code.
+ * `records.map(...)` and a body that returns one object read almost identically,
+ * and a detector that guessed from destructuring — `{ records }` versus
+ * `{ record }` — would be reading a *parameter name*, which is the author's to
+ * choose and which minification, a rename, or a rest parameter changes without
+ * changing what the function computes. Guess wrong towards `record` and an
+ * aggregation is called 102,520 times and returns 102,520 partial answers, none
+ * of which fails; guess wrong towards `batch` and a per-record function is handed
+ * an array and reads `undefined` off every property. Both commit. Neither errors.
+ * So the mode is a field somebody set, and the cost of setting it is one control
+ * in the editor.
+ *
+ * ## Why a closed list rather than `streaming?: boolean`
+ *
+ * The identical argument {@link WORKFLOW_CALL_MODES} makes one level up. A flag
+ * beside a future third calling convention — a windowed transform, a keyed one —
+ * is two optional booleans whose combinations nobody defined, and each reader
+ * invents its own rule for which wins. A closed list with an exhaustiveness guard
+ * ({@link unreachableTransformMode}) makes a third convention a compile error
+ * naming the files that have to answer for it: the harness that generates the
+ * call, the runner that chooses a transport, and the two runners that consume
+ * the result.
+ *
+ * ## What the default has to be, and why it is not a choice
+ *
+ * Absent means {@link CatalogTransform.mode} was never set, which is every
+ * transform stored before this field existed, and every one of them is a function
+ * over the whole batch — the harness handed it `records` and there was no other
+ * shape to write. Reading absence as anything else would silently change what a
+ * deployment's existing loads compute. Read it through {@link transformMode}
+ * rather than defaulting it a second time.
+ */
+exports.TRANSFORM_MODES = [
+    /**
+     * The code is called **once**, with every record the node received.
+     *
+     * What every stored transform is, and what aggregating, deduplicating,
+     * sorting and joining require: none of them can be done a row at a time, and
+     * chunking the calls would not fail — it would return one answer per chunk and
+     * commit. The whole input is therefore in the running process's heap, which is
+     * the honest cost of the promise.
+     */
+    'batch',
+    /**
+     * The code is called **once per record**, and never sees the batch.
+     *
+     * What a rename, a projection or a normalisation is by construction — and,
+     * since `WORKFLOW_FILTER_COLUMN_PATTERN` and `property-names.ts` both refuse a
+     * header with a space in it, what every DPAS file this catalog ingests needs
+     * before anything else can touch it. The records arrive as a stream and the
+     * rows leave as one, so nothing anywhere holds the dataset.
+     */
+    'record',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isTransformMode(value) {
+    return exports.TRANSFORM_MODES.some((mode) => mode === value);
+}
+/**
+ * {@link unreachableCallMode}, for transforms, and for the identical reason.
+ *
+ * Every branch over {@link TransformMode} ends here, so a third calling
+ * convention added to the list without a harness to generate it, a transport to
+ * carry it and a consumer to read its output is a type error naming the file. It
+ * throws as well, because a mode arrives as JSON out of a column and a build
+ * older than the data is a thing that happens.
+ */
+function unreachableTransformMode(mode, where) {
+    throw new Error(`${where} has no rule for the transform mode ${JSON.stringify(mode)}. It was added to TRANSFORM_MODES without teaching this code how to call user code written for it, and guessing would run somebody's transform under a contract they did not write it against.`);
+}
+/**
+ * The mode this transform runs in, with the default applied once.
+ *
+ * Absent means `'batch'` — see {@link TRANSFORM_MODES}. One function so that the
+ * store, the runner, the two consumers, the editor and the try pane cannot each
+ * carry their own `?? 'batch'` and have one of them drift.
+ */
+function transformMode(transform) {
+    return transform.mode ?? 'batch';
+}
+/**
+ * Why this transform cannot run in the mode it declares, if it cannot.
+ *
+ * Two combinations are representable and neither can work, so both are refused
+ * at the point somebody presses save rather than at three in the morning when a
+ * schedule fires. `undefined` means there is nothing wrong.
+ *
+ * Asked in both places on purpose. The controller asks so the author is told
+ * while they are still looking at the code; the runner asks because a row can
+ * reach it that no controller in this build ever validated — promoted from
+ * another environment, restored from a backup, written by an older version — and
+ * the failure a runner must never have is the silent one where a per-record
+ * module is handed an array and quietly reads `undefined` off every property.
+ */
+function recordModeRefusal(transform) {
+    if (transformMode(transform) !== 'record')
+        return undefined;
+    if (transform.language === 'python') {
+        return 'A per-record transform cannot be written in Python yet. The Python harness writes `def transform(records, context):` around the code, so a Python transform never states its own signature and there is no second `def` for the per-record shape — see TRANSFORM_MODES. Use javascript or typescript for a per-record transform, or leave this one as a whole-batch transform.';
+    }
+    if ((0, transform_shape_1.transformShape)(transform.code) === 'body') {
+        return 'A per-record transform must be a module that exports a function — `export default function transform({ record, context }) { … }` — and this code has no `export` at the start of a statement, so the catalog would run it as a bare function body. A body is handed `records`, the whole array, by the wrapper the catalog writes around it; there is no honest way to give it one record under a name it never wrote. Add the `export`, or set this transform back to whole-batch.';
+    }
+    return undefined;
+}
+/**
+ * Whether this runner can stream a per-record transform.
+ *
+ * The method rather than a flag, exactly as {@link supportsTransformRevisions}
+ * argues one interface along: a flag is a claim and a method is the thing
+ * itself. A runner that answers `false` still runs `'record'` transforms — the
+ * consumers buffer and call {@link TransformRunner.run} — so this is a question
+ * about *how much is held*, never about whether the load works.
+ */
+function supportsTransformStreaming(runner) {
+    return typeof runner.runStream === 'function';
+}
 exports.TRANSFORM_RUNNER = Symbol('TRANSFORM_RUNNER');
 /**
  * The number in {@link CatalogCodeContext.contract}.

package/dist/client.d.ts

@@ -153,9 +153,9 @@ export declare const catalogRoutes: {
     readonly traces: () => string;
     readonly trace: (id: string) => string;
 };
-export type { CatalogConnection, CatalogConnector, ConnectionCheck, CatalogTransform, CatalogTransformFunction, CatalogTransformInput, CatalogWorkflow, CatalogWorkflowCapabilities, CatalogWorkflowRelease, ConnectorKind, ConnectorRun, TransformLanguage, TransformResult, CallableWorkflowRef, WorkflowBranchLabel, WorkflowCallEnvelope, WorkflowCallMode, WorkflowCallNode, WorkflowCallOutput, WorkflowEdge, WorkflowExecutionMode, WorkflowFilterAll, WorkflowFilterAny, WorkflowFilterComparison, WorkflowFilterGroup, WorkflowFilterNode, WorkflowFilterOneOf, WorkflowFilterOperator, WorkflowFilterPredicate, WorkflowFilterPredicateKind, WorkflowFilterPresence, WorkflowFilterValue, WorkflowGraph, WorkflowEnvPredicate, WorkflowIfNode, WorkflowIfPredicate, WorkflowIssueCode, WorkflowNode, WorkflowNodeKind, WorkflowNodeOutcome, WorkflowPredicateKind, WorkflowRenameNode, WorkflowRenameUnnamed, WorkflowRowCountPredicate, WorkflowRunOrderEntry, WorkflowSinkNode, WorkflowSkipReason, WorkflowSourceNode, WorkflowStageRef, WorkflowTransformNode, WorkflowValidationIssue, CatalogReusableNode, CatalogReusableNodeUse, ReusableNodeBody, ReusableNodeKind, ReusableNodeRef, ReusableSinkBody, ReusableSourceBody, SourceFormat, VersionPinCopy, } from './catalog.pipeline';
+export type { CatalogConnection, CatalogConnector, ConnectionCheck, CatalogTransform, CatalogTransformFunction, CatalogTransformInput, CatalogRecordTransformFunction, CatalogRecordTransformInput, CatalogWorkflow, CatalogWorkflowCapabilities, CatalogWorkflowRelease, ConnectorKind, ConnectorRun, TransformLanguage, TransformMode, TransformResult, CallableWorkflowRef, WorkflowBranchLabel, WorkflowCallEnvelope, WorkflowCallMode, WorkflowCallNode, WorkflowCallOutput, WorkflowEdge, WorkflowExecutionMode, WorkflowFilterAll, WorkflowFilterAny, WorkflowFilterComparison, WorkflowFilterGroup, WorkflowFilterNode, WorkflowFilterOneOf, WorkflowFilterOperator, WorkflowFilterPredicate, WorkflowFilterPredicateKind, WorkflowFilterPresence, WorkflowFilterValue, WorkflowGraph, WorkflowEnvPredicate, WorkflowIfNode, WorkflowIfPredicate, WorkflowIssueCode, WorkflowNode, WorkflowNodeKind, WorkflowNodeOutcome, WorkflowPredicateKind, WorkflowRenameNode, WorkflowRenameUnnamed, WorkflowRowCountPredicate, WorkflowRunOrderEntry, WorkflowSinkNode, WorkflowSkipReason, WorkflowSourceNode, WorkflowStageRef, WorkflowTransformNode, WorkflowValidationIssue, CatalogReusableNode, CatalogReusableNodeUse, ReusableNodeBody, ReusableNodeKind, ReusableNodeRef, ReusableSinkBody, ReusableSourceBody, SourceFormat, VersionPinCopy, } from './catalog.pipeline';
 export { type TransformShape, transformDeclaresModule, transformShape, } from './transform-shape';
-export { CONNECTOR_KINDS, isConnectorKind, isSourceFormat, isTransformLanguage, SOURCE_FORMATS, isWorkflowEdge, isWorkflowNode, liveWorkflowVersion, REDACTED_SECRET, TRANSFORM_LANGUAGES, readWorkflowCallOutput, WORKFLOW_CALL_CONTRACT, WORKFLOW_CALL_MODES, isWorkflowCallMode, unreachableCallMode, workflowCallMode, applyReusableNode, reusableNodeBodyOf, isReusableNodeBody, isReusableNodeKind, REUSABLE_NODE_KINDS, NODE_KIND_IS_REUSABLE, nodeKindIsReusable, unreachableReusableNodeKind, describeLiveVersion, describeVersionPin, } from './catalog.pipeline';
+export { CONNECTOR_KINDS, isConnectorKind, isSourceFormat, isTransformLanguage, isTransformMode, TRANSFORM_MODES, transformMode, recordModeRefusal, SOURCE_FORMATS, isWorkflowEdge, isWorkflowNode, liveWorkflowVersion, REDACTED_SECRET, TRANSFORM_LANGUAGES, readWorkflowCallOutput, WORKFLOW_CALL_CONTRACT, WORKFLOW_CALL_MODES, isWorkflowCallMode, unreachableCallMode, workflowCallMode, applyReusableNode, reusableNodeBodyOf, isReusableNodeBody, isReusableNodeKind, REUSABLE_NODE_KINDS, NODE_KIND_IS_REUSABLE, nodeKindIsReusable, unreachableReusableNodeKind, describeLiveVersion, describeVersionPin, } from './catalog.pipeline';
 /**
  * The workflow validator, shipped to the browser deliberately.
  *