@sequenceholdings/pipeline-spec 0.1.0

package/dist/bodies/transformation.d.ts

@@ -0,0 +1,397 @@
+import { z } from 'zod';
+import { type CatalogBinding } from '../catalog-binding.js';
+import { type ColumnsOrRef } from '../columns.js';
+/**
+ * Transformation stages are where typing begins: inputs by logical asset
+ * reference (including the `lakebase_cdf` kind for reverse-sync), engine
+ * declaration, and strictly typed outputs whose contracts later compile to
+ * DLT expectations and Delta constraints.
+ *
+ * ## Quarantine semantics
+ *
+ * Rows failing a `quarantine`-posture check land in a platform-derived
+ * `<output>__quarantine` sibling table (see `QUARANTINE_SUFFIX`). The name
+ * derivation is defined HERE (M1) so later compilation matches — e.g.
+ * `silver.players` quarantines into `silver.players__quarantine`.
+ */
+export declare const TRANSFORMATION_ENGINES: readonly ["dlt", "spark-job", "polars"];
+export declare const transformationEngineSchema: z.ZodEnum<{
+    dlt: "dlt";
+    "spark-job": "spark-job";
+    polars: "polars";
+}>;
+export type TransformationEngine = z.infer<typeof transformationEngineSchema>;
+export declare const outputAssetNameSchema: z.ZodString;
+/**
+ * Reference to another stage's asset: an ingestion feed (`feed`) or a
+ * transformation output (`output`) — exactly one. `columns` narrows the input
+ * to the subset actually consumed (checked against the producer's declared
+ * columns by graph validation). `declared_loose` opts out of the column-subset
+ * check for schema-fluid sources.
+ */
+declare const stageInputSchema: z.ZodObject<{
+    stage: z.ZodString;
+    feed: z.ZodOptional<z.ZodString>;
+    output: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    freshness_requirement: z.ZodOptional<z.ZodString>;
+    declared_loose: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type StageInput = z.infer<typeof stageInputSchema>;
+/**
+ * Platform-defined CDC envelope columns present on every Lakebase CDF history
+ * table, IN ADDITION to the declared business columns. Authors never
+ * re-declare these; the platform guarantees them.
+ *
+ * `_pg_change_type` values: `insert`, `update_preimage`, `update_postimage`,
+ * `delete`; the commit columns order and deduplicate events.
+ */
+export declare const LAKEBASE_CDF_ENVELOPE_COLUMNS: {
+    readonly _pg_change_type: "string";
+    readonly _pg_commit_lsn: "string";
+    readonly _pg_commit_ts: "timestamp";
+};
+/**
+ * A CDF-enabled Lakebase table input — the reverse-sync path (Postgres manual
+ * overlay → Delta history → transformation).
+ *
+ * The contract is an **envelope, not a row schema**: the input declares the
+ * business columns it consumes PLUS the platform-defined CDC envelope
+ * (`LAKEBASE_CDF_ENVELOPE_COLUMNS`), and a `fold` semantic:
+ *
+ * - `latest_state` — the platform-documented fold to current rows by key
+ *   (last `update_postimage`/`insert` per key, `delete` removes).
+ * - `events` — the raw CDC event stream.
+ *
+ * Business-column types come from the declared schema — never inferred.
+ * `manual.*` sources are Atlas-owned tables with no ORM YAML, so columns are
+ * ALWAYS declared explicitly. (ORM-YAML-derived typing is deferred until an
+ * ORM→Delta type mapping exists — not assumed.)
+ */
+declare const lakebaseCdfInputSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"lakebase_cdf">;
+    table: z.ZodString;
+    columns: z.ZodUnion<readonly [z.ZodObject<{
+        schema_ref: z.ZodString;
+    }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodUnion<readonly [z.ZodEnum<{
+            string: "string";
+            boolean: "boolean";
+            uuid: "uuid";
+            int: "int";
+            long: "long";
+            numeric: "numeric";
+            double: "double";
+            timestamp: "timestamp";
+            date: "date";
+            json: "json";
+        }>, z.ZodEnum<{
+            float: "float";
+            timestamp_ntz: "timestamp_ntz";
+            array: "array";
+            map: "map";
+            struct: "struct";
+            binary: "binary";
+        }>, z.ZodString]>;
+        nullable: z.ZodDefault<z.ZodBoolean>;
+        key: z.ZodDefault<z.ZodBoolean>;
+        domain: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        description: z.ZodOptional<z.ZodString>;
+        on_violation: z.ZodDefault<z.ZodEnum<{
+            fail: "fail";
+            quarantine: "quarantine";
+            warn: "warn";
+        }>>;
+    }, z.core.$strict>>]>;
+    fold: z.ZodEnum<{
+        latest_state: "latest_state";
+        events: "events";
+    }>;
+}, z.core.$strict>;
+export type LakebaseCdfInput = z.infer<typeof lakebaseCdfInputSchema>;
+/**
+ * Discriminated input union: a stage-asset reference or a Lakebase CDF table.
+ * (`kind` discriminates; stage references have no `kind`.)
+ */
+export declare const transformationInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"lakebase_cdf">;
+    table: z.ZodString;
+    columns: z.ZodUnion<readonly [z.ZodObject<{
+        schema_ref: z.ZodString;
+    }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodUnion<readonly [z.ZodEnum<{
+            string: "string";
+            boolean: "boolean";
+            uuid: "uuid";
+            int: "int";
+            long: "long";
+            numeric: "numeric";
+            double: "double";
+            timestamp: "timestamp";
+            date: "date";
+            json: "json";
+        }>, z.ZodEnum<{
+            float: "float";
+            timestamp_ntz: "timestamp_ntz";
+            array: "array";
+            map: "map";
+            struct: "struct";
+            binary: "binary";
+        }>, z.ZodString]>;
+        nullable: z.ZodDefault<z.ZodBoolean>;
+        key: z.ZodDefault<z.ZodBoolean>;
+        domain: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        description: z.ZodOptional<z.ZodString>;
+        on_violation: z.ZodDefault<z.ZodEnum<{
+            fail: "fail";
+            quarantine: "quarantine";
+            warn: "warn";
+        }>>;
+    }, z.core.$strict>>]>;
+    fold: z.ZodEnum<{
+        latest_state: "latest_state";
+        events: "events";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    stage: z.ZodString;
+    feed: z.ZodOptional<z.ZodString>;
+    output: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    freshness_requirement: z.ZodOptional<z.ZodString>;
+    declared_loose: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>]>;
+export type TransformationInput = z.infer<typeof transformationInputSchema>;
+export declare function isLakebaseCdfInput(input: TransformationInput): input is LakebaseCdfInput;
+/**
+ * How the output relation is written — consumed by writer-pattern validation
+ * when compilation lands (M6):
+ * - `overwrite` — full recompute each run (materialized-view-style).
+ * - `append` — append-only (event/log outputs).
+ * - `auto_cdc` — merge by key with CDC semantics.
+ */
+export declare const WRITE_PATTERNS: readonly ["overwrite", "append", "auto_cdc"];
+export declare const writePatternSchema: z.ZodEnum<{
+    overwrite: "overwrite";
+    append: "append";
+    auto_cdc: "auto_cdc";
+}>;
+export type WritePattern = z.infer<typeof writePatternSchema>;
+/** A writer owns one disjoint value of a non-null string discriminator. */
+export declare const writeScopeSchema: z.ZodObject<{
+    column: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strict>;
+export declare const transformationOutputSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    columns: z.ZodUnion<readonly [z.ZodObject<{
+        schema_ref: z.ZodString;
+    }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodUnion<readonly [z.ZodEnum<{
+            string: "string";
+            boolean: "boolean";
+            uuid: "uuid";
+            int: "int";
+            long: "long";
+            numeric: "numeric";
+            double: "double";
+            timestamp: "timestamp";
+            date: "date";
+            json: "json";
+        }>, z.ZodEnum<{
+            float: "float";
+            timestamp_ntz: "timestamp_ntz";
+            array: "array";
+            map: "map";
+            struct: "struct";
+            binary: "binary";
+        }>, z.ZodString]>;
+        nullable: z.ZodDefault<z.ZodBoolean>;
+        key: z.ZodDefault<z.ZodBoolean>;
+        domain: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        description: z.ZodOptional<z.ZodString>;
+        on_violation: z.ZodDefault<z.ZodEnum<{
+            fail: "fail";
+            quarantine: "quarantine";
+            warn: "warn";
+        }>>;
+    }, z.core.$strict>>]>;
+    on_type_violation: z.ZodDefault<z.ZodEnum<{
+        fail: "fail";
+        quarantine: "quarantine";
+        warn: "warn";
+    }>>;
+    compatibility: z.ZodDefault<z.ZodEnum<{
+        "additive-only": "additive-only";
+        versioned: "versioned";
+    }>>;
+    write_pattern: z.ZodEnum<{
+        overwrite: "overwrite";
+        append: "append";
+        auto_cdc: "auto_cdc";
+    }>;
+    write_scope: z.ZodOptional<z.ZodObject<{
+        column: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TransformationOutput = z.infer<typeof transformationOutputSchema>;
+/** Manual-only, or cron / after (both allowed for cron floor + dependency chaining). */
+export declare const transformationTriggerSchema: z.ZodObject<{
+    manual: z.ZodOptional<z.ZodLiteral<true>>;
+    cron: z.ZodOptional<z.ZodString>;
+    after: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    refresh_serving: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type TransformationTrigger = z.infer<typeof transformationTriggerSchema>;
+export declare const transformationBodyShape: {
+    engine: z.ZodEnum<{
+        dlt: "dlt";
+        "spark-job": "spark-job";
+        polars: "polars";
+    }>;
+    /**
+     * The stage's lineage edges — what it consumes. An empty array is legal
+     * only as a scaffold state (`seq-studio pipeline init`); graph validation
+     * emits a `no_inputs_declared` warning until real inputs are wired.
+     */
+    inputs: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"lakebase_cdf">;
+        table: z.ZodString;
+        columns: z.ZodUnion<readonly [z.ZodObject<{
+            schema_ref: z.ZodString;
+        }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodUnion<readonly [z.ZodEnum<{
+                string: "string";
+                boolean: "boolean";
+                uuid: "uuid";
+                int: "int";
+                long: "long";
+                numeric: "numeric";
+                double: "double";
+                timestamp: "timestamp";
+                date: "date";
+                json: "json";
+            }>, z.ZodEnum<{
+                float: "float";
+                timestamp_ntz: "timestamp_ntz";
+                array: "array";
+                map: "map";
+                struct: "struct";
+                binary: "binary";
+            }>, z.ZodString]>;
+            nullable: z.ZodDefault<z.ZodBoolean>;
+            key: z.ZodDefault<z.ZodBoolean>;
+            domain: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+            description: z.ZodOptional<z.ZodString>;
+            on_violation: z.ZodDefault<z.ZodEnum<{
+                fail: "fail";
+                quarantine: "quarantine";
+                warn: "warn";
+            }>>;
+        }, z.core.$strict>>]>;
+        fold: z.ZodEnum<{
+            latest_state: "latest_state";
+            events: "events";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        stage: z.ZodString;
+        feed: z.ZodOptional<z.ZodString>;
+        output: z.ZodOptional<z.ZodString>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        freshness_requirement: z.ZodOptional<z.ZodString>;
+        declared_loose: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+    trigger: z.ZodObject<{
+        manual: z.ZodOptional<z.ZodLiteral<true>>;
+        cron: z.ZodOptional<z.ZodString>;
+        after: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        refresh_serving: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    outputs: z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        columns: z.ZodUnion<readonly [z.ZodObject<{
+            schema_ref: z.ZodString;
+        }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodUnion<readonly [z.ZodEnum<{
+                string: "string";
+                boolean: "boolean";
+                uuid: "uuid";
+                int: "int";
+                long: "long";
+                numeric: "numeric";
+                double: "double";
+                timestamp: "timestamp";
+                date: "date";
+                json: "json";
+            }>, z.ZodEnum<{
+                float: "float";
+                timestamp_ntz: "timestamp_ntz";
+                array: "array";
+                map: "map";
+                struct: "struct";
+                binary: "binary";
+            }>, z.ZodString]>;
+            nullable: z.ZodDefault<z.ZodBoolean>;
+            key: z.ZodDefault<z.ZodBoolean>;
+            domain: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+            description: z.ZodOptional<z.ZodString>;
+            on_violation: z.ZodDefault<z.ZodEnum<{
+                fail: "fail";
+                quarantine: "quarantine";
+                warn: "warn";
+            }>>;
+        }, z.core.$strict>>]>;
+        on_type_violation: z.ZodDefault<z.ZodEnum<{
+            fail: "fail";
+            quarantine: "quarantine";
+            warn: "warn";
+        }>>;
+        compatibility: z.ZodDefault<z.ZodEnum<{
+            "additive-only": "additive-only";
+            versioned: "versioned";
+        }>>;
+        write_pattern: z.ZodEnum<{
+            overwrite: "overwrite";
+            append: "append";
+            auto_cdc: "auto_cdc";
+        }>;
+        write_scope: z.ZodOptional<z.ZodObject<{
+            column: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    entrypoint: z.ZodString;
+    config: z.ZodOptional<z.ZodObject<{
+        catalog: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            default: z.ZodString;
+            by_target: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>]>>;
+        history_catalog: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            default: z.ZodString;
+            by_target: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>]>>;
+        silver_catalog: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            default: z.ZodString;
+            by_target: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>]>>;
+        python_environment_version: z.ZodOptional<z.ZodEnum<{
+            3: "3";
+            4: "4";
+        }>>;
+    }, z.core.$catchall<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>>;
+};
+/** Structural slice of a stage spec the transformation refinement needs. */
+export interface TransformationBody {
+    readonly engine: TransformationEngine;
+    readonly inputs: readonly TransformationInput[];
+    readonly trigger: TransformationTrigger;
+    readonly outputs: Record<string, {
+        columns: ColumnsOrRef;
+        write_scope?: z.infer<typeof writeScopeSchema>;
+    }>;
+    readonly config?: Readonly<Record<string, string | number | boolean | CatalogBinding>>;
+}
+/** Cross-field validation for `type: transformation` bodies (invoked from the envelope refinement). */
+export declare function refineTransformationBody(body: TransformationBody, ctx: z.RefinementCtx): void;
+export {};
+//# sourceMappingURL=transformation.d.ts.map

package/dist/bodies/transformation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformation.d.ts","sourceRoot":"","sources":["../../src/bodies/transformation.ts"],"names":[],"mappings":"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"}

package/dist/bodies/transformation.js

@@ -0,0 +1,278 @@
+import { z } from 'zod';
+import { catalogBindingSchema } from '../catalog-binding.js';
+import { CRON_PATTERN, OUTPUT_ASSET_PATTERN, QUALIFIED_TABLE_PATTERN, REPORT_ASSET_PATTERN, QUARANTINE_SUFFIX, STAGE_ID_PATTERN, } from '../constants.js';
+import { columnIdentifierSchema, columnsOrRefSchema, identifierSchema, isSchemaRef, nullableKeyColumns, } from '../columns.js';
+import { isoDurationSchema, repoRelativePathSchema } from './ingestion.js';
+/**
+ * Transformation stages are where typing begins: inputs by logical asset
+ * reference (including the `lakebase_cdf` kind for reverse-sync), engine
+ * declaration, and strictly typed outputs whose contracts later compile to
+ * DLT expectations and Delta constraints.
+ *
+ * ## Quarantine semantics
+ *
+ * Rows failing a `quarantine`-posture check land in a platform-derived
+ * `<output>__quarantine` sibling table (see `QUARANTINE_SUFFIX`). The name
+ * derivation is defined HERE (M1) so later compilation matches — e.g.
+ * `silver.players` quarantines into `silver.players__quarantine`.
+ */
+export const TRANSFORMATION_ENGINES = ['dlt', 'spark-job', 'polars'];
+export const transformationEngineSchema = z.enum(TRANSFORMATION_ENGINES);
+const stageRefSchema = z
+    .string()
+    .regex(STAGE_ID_PATTERN, 'must be a stage id (kebab-case slug)');
+export const outputAssetNameSchema = z
+    .string()
+    .regex(OUTPUT_ASSET_PATTERN, "output assets must match '^(silver|gold|report)\\.[a-z][a-z0-9_]*$'");
+/**
+ * Reference to another stage's asset: an ingestion feed (`feed`) or a
+ * transformation output (`output`) — exactly one. `columns` narrows the input
+ * to the subset actually consumed (checked against the producer's declared
+ * columns by graph validation). `declared_loose` opts out of the column-subset
+ * check for schema-fluid sources.
+ */
+const stageInputSchema = z.strictObject({
+    stage: stageRefSchema,
+    feed: identifierSchema.optional(),
+    output: outputAssetNameSchema.optional(),
+    columns: z.array(columnIdentifierSchema).min(1).optional(),
+    /** Max acceptable staleness of the consumed asset. */
+    freshness_requirement: isoDurationSchema.optional(),
+    /** Skip column-subset validation — the input consumes whatever the producer emits. */
+    declared_loose: z.boolean().optional(),
+});
+/**
+ * Platform-defined CDC envelope columns present on every Lakebase CDF history
+ * table, IN ADDITION to the declared business columns. Authors never
+ * re-declare these; the platform guarantees them.
+ *
+ * `_pg_change_type` values: `insert`, `update_preimage`, `update_postimage`,
+ * `delete`; the commit columns order and deduplicate events.
+ */
+export const LAKEBASE_CDF_ENVELOPE_COLUMNS = {
+    _pg_change_type: 'string',
+    _pg_commit_lsn: 'string',
+    _pg_commit_ts: 'timestamp',
+};
+/**
+ * A CDF-enabled Lakebase table input — the reverse-sync path (Postgres manual
+ * overlay → Delta history → transformation).
+ *
+ * The contract is an **envelope, not a row schema**: the input declares the
+ * business columns it consumes PLUS the platform-defined CDC envelope
+ * (`LAKEBASE_CDF_ENVELOPE_COLUMNS`), and a `fold` semantic:
+ *
+ * - `latest_state` — the platform-documented fold to current rows by key
+ *   (last `update_postimage`/`insert` per key, `delete` removes).
+ * - `events` — the raw CDC event stream.
+ *
+ * Business-column types come from the declared schema — never inferred.
+ * `manual.*` sources are Atlas-owned tables with no ORM YAML, so columns are
+ * ALWAYS declared explicitly. (ORM-YAML-derived typing is deferred until an
+ * ORM→Delta type mapping exists — not assumed.)
+ */
+const lakebaseCdfInputSchema = z.strictObject({
+    kind: z.literal('lakebase_cdf'),
+    /** `<schema>.<table>` of the CDF-enabled Lakebase source (e.g. `manual.retail_customers`). */
+    table: z
+        .string()
+        .regex(QUALIFIED_TABLE_PATTERN, "must be '<schema>.<table>' (e.g. manual.retail_customers)"),
+    /** Business columns consumed, with types — REQUIRED, never inferred. */
+    columns: columnsOrRefSchema,
+    fold: z.enum(['latest_state', 'events']),
+});
+/**
+ * Discriminated input union: a stage-asset reference or a Lakebase CDF table.
+ * (`kind` discriminates; stage references have no `kind`.)
+ */
+export const transformationInputSchema = z.union([lakebaseCdfInputSchema, stageInputSchema]);
+export function isLakebaseCdfInput(input) {
+    return 'kind' in input && input.kind === 'lakebase_cdf';
+}
+/**
+ * How the output relation is written — consumed by writer-pattern validation
+ * when compilation lands (M6):
+ * - `overwrite` — full recompute each run (materialized-view-style).
+ * - `append` — append-only (event/log outputs).
+ * - `auto_cdc` — merge by key with CDC semantics.
+ */
+export const WRITE_PATTERNS = ['overwrite', 'append', 'auto_cdc'];
+export const writePatternSchema = z.enum(WRITE_PATTERNS);
+/** A writer owns one disjoint value of a non-null string discriminator. */
+export const writeScopeSchema = z.strictObject({
+    column: columnIdentifierSchema,
+    value: z.string().min(1),
+});
+export const transformationOutputSchema = z.strictObject({
+    description: z.string().optional(),
+    /** The output's typed contract — inline columns or a `schema_ref`. */
+    columns: columnsOrRefSchema,
+    /**
+     * Row posture when a value violates its column type: `fail` the batch
+     * (default), `quarantine` into `<output>__quarantine`, or `warn`.
+     */
+    on_type_violation: z.enum(['fail', 'quarantine', 'warn']).default('fail'),
+    /**
+     * Contract evolution posture: `additive-only` (default) — breaking changes
+     * fail validation; `versioned` — breaking changes allowed with an explicit
+     * version bump (enforced by the CI gate via `diffContracts`).
+     */
+    compatibility: z.enum(['additive-only', 'versioned']).default('additive-only'),
+    write_pattern: writePatternSchema,
+    /** Every write, including snapshot deletions, must stay inside this scope. */
+    write_scope: writeScopeSchema.optional(),
+});
+/** Manual-only, or cron / after (both allowed for cron floor + dependency chaining). */
+export const transformationTriggerSchema = z.strictObject({
+    /** Explicit opt-in to run-now only; useful for isolated parity and backfill jobs. */
+    manual: z.literal(true).optional(),
+    cron: z.string().regex(CRON_PATTERN, 'must be a cron expression (5–7 fields)').optional(),
+    after: z
+        .array(stageRefSchema)
+        .min(1)
+        .refine((after) => new Set(after).size === after.length, 'after must not declare the same upstream stage twice')
+        .optional(),
+    /** Refresh already provisioned serving stages that read this writer's outputs. */
+    refresh_serving: z.array(stageRefSchema).min(1)
+        .refine((stages) => new Set(stages).size === stages.length, 'refresh_serving must not repeat a stage')
+        .optional(),
+});
+/** Opaque per-engine scalar config plus platform-owned catalog bindings. */
+const engineConfigValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+const engineConfigSchema = z
+    .object({
+    catalog: catalogBindingSchema.optional(),
+    history_catalog: catalogBindingSchema.optional(),
+    silver_catalog: catalogBindingSchema.optional(),
+    /** Explicit serverless Python environment; omitted preserves version 3. */
+    python_environment_version: z.enum(['3', '4']).optional(),
+})
+    .catchall(engineConfigValueSchema);
+export const transformationBodyShape = {
+    engine: transformationEngineSchema,
+    /**
+     * The stage's lineage edges — what it consumes. An empty array is legal
+     * only as a scaffold state (`seq-studio pipeline init`); graph validation
+     * emits a `no_inputs_declared` warning until real inputs are wired.
+     */
+    inputs: z.array(transformationInputSchema),
+    trigger: transformationTriggerSchema,
+    outputs: z.record(outputAssetNameSchema, transformationOutputSchema),
+    entrypoint: repoRelativePathSchema,
+    config: engineConfigSchema.optional(),
+};
+const CATALOG_CONFIG_KEYS = ['bronze_catalog'];
+function refineCatalogConfigKeys(config, ctx) {
+    if (!config)
+        return;
+    for (const key of CATALOG_CONFIG_KEYS) {
+        if (!(key in config))
+            continue;
+        const parsed = identifierSchema.safeParse(config[key]);
+        if (parsed.success)
+            continue;
+        ctx.addIssue({
+            code: 'custom',
+            path: ['config', key],
+            message: parsed.error.issues[0]?.message ?? 'must be a lowercase identifier (a-z, 0-9, _)',
+        });
+    }
+}
+/** Cross-field validation for `type: transformation` bodies (invoked from the envelope refinement). */
+export function refineTransformationBody(body, ctx) {
+    refineCatalogConfigKeys(body.config, ctx);
+    if (body.config?.python_environment_version !== undefined && body.engine !== 'polars') {
+        ctx.addIssue({ code: 'custom', path: ['config', 'python_environment_version'], message: 'python_environment_version requires a polars producer' });
+    }
+    if (body.trigger.refresh_serving && body.engine !== 'spark-job' && body.engine !== 'polars') {
+        ctx.addIssue({ code: 'custom', path: ['trigger', 'refresh_serving'], message: 'refresh_serving requires a spark-job or polars producer' });
+    }
+    if (body.trigger.manual && (body.trigger.cron || body.trigger.after || body.trigger.refresh_serving)) {
+        ctx.addIssue({ code: 'custom', path: ['trigger'], message: 'manual cannot be combined with cron, after, or refresh_serving' });
+    }
+    if (!body.trigger.manual && !body.trigger.cron && (!body.trigger.after || body.trigger.after.length === 0)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['trigger'],
+            message: 'a transformation must declare a trigger: cron, after (upstream stages), both, or manual',
+        });
+    }
+    body.inputs.forEach((input, index) => {
+        if (isLakebaseCdfInput(input))
+            return;
+        const hasFeed = input.feed !== undefined;
+        const hasOutput = input.output !== undefined;
+        if (hasFeed === hasOutput) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['inputs', index],
+                message: "a stage input must reference exactly one of 'feed' (ingestion feed) or 'output' (transformation output)",
+            });
+        }
+    });
+    // Inventory-driven raw passthroughs (FIS/JH report plants) write table
+    // names from code. Declaring each report.* output here is what OOM'd
+    // pipeline-deploy during bundle deploy.
+    if (Object.keys(body.outputs).length === 0 && body.config?.raw_passthrough !== true) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['outputs'],
+            message: 'a transformation must declare at least one output',
+        });
+    }
+    for (const [asset, output] of Object.entries(body.outputs)) {
+        if (REPORT_ASSET_PATTERN.test(asset) && body.config?.raw_passthrough !== true) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['config', 'raw_passthrough'],
+                message: `report output '${asset}' requires config.raw_passthrough: true`,
+            });
+        }
+        if (!REPORT_ASSET_PATTERN.test(asset) && body.config?.raw_passthrough === true) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['outputs', asset],
+                message: `raw passthrough stages may only declare report.* outputs (got '${asset}')`,
+            });
+        }
+        refineWriteScope({ engine: body.engine, asset, output, ctx });
+        if (asset.endsWith(QUARANTINE_SUFFIX)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['outputs', asset],
+                message: `'${QUARANTINE_SUFFIX}' names are platform-derived quarantine tables and cannot be declared`,
+            });
+        }
+        if (isSchemaRef(output.columns))
+            continue;
+        const badKeys = nullableKeyColumns(output.columns);
+        for (const column of badKeys) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['outputs', asset, 'columns', column, 'nullable'],
+                message: `key column '${column}' must be nullable: false`,
+            });
+        }
+    }
+}
+/** Scope declarations are valid only for explicit atomic job writers. */
+function refineWriteScope({ engine, asset, output, ctx }) {
+    if (!output.write_scope)
+        return;
+    if (engine !== 'spark-job' && engine !== 'polars') {
+        ctx.addIssue({ code: 'custom', path: ['outputs', asset, 'write_scope'],
+            message: 'scoped writers require spark-job or polars with source-scoped atomic writes' });
+    }
+    if (isSchemaRef(output.columns))
+        return;
+    const column = output.columns[output.write_scope.column];
+    if (!column || column.type !== 'string' || column.nullable) {
+        ctx.addIssue({ code: 'custom', path: ['outputs', asset, 'write_scope'],
+            message: 'write_scope.column must name a non-nullable string output column' });
+    }
+    else if (column.domain && !column.domain.includes(output.write_scope.value)) {
+        ctx.addIssue({ code: 'custom', path: ['outputs', asset, 'write_scope', 'value'],
+            message: 'write_scope.value must belong to the discriminator column domain' });
+    }
+}
+//# sourceMappingURL=transformation.js.map