@sequenceholdings/pipeline-spec 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @sequenceholdings/pipeline-spec
+
+Schema and offline validation support for Sequence Managed Pipeline stage
+specifications.
+
+This package is published so `@sequenceholdings/studio-cli` can load its
+pipeline commands in standalone repositories. Its JavaScript module export is
+an internal implementation detail, not a supported public SDK contract. Author
+and validate pipeline repositories through `seq-studio pipeline`.
+
+## Install
+
+Install the CLI and its pipeline-spec peer dependency in the repository that
+owns your pipeline:
+
+```bash
+pnpm add --save-dev \
+  @sequenceholdings/studio-cli \
+  @sequenceholdings/pipeline-spec
+```
+
+## Validate a pipeline repository
+
+Run validation from the repository root:
+
+```bash
+pnpm exec seq-studio pipeline validate .
+```
+
+The validator discovers `*.stage.yml` files recursively. A stage specification
+describes one deployable unit and its inputs, outputs, runtime, ownership, and
+environment policy. For example:
+
+```yaml
+schema_version: 1
+stage: ingest-events
+title: Event ingestion
+description: Pulls event records into the bronze landing zone.
+type: ingestion
+owners:
+  - data-platform@example.com
+criticality: standard
+environments:
+  - staging
+runtime: databricks
+source:
+  system: events_api
+  credential: events_api_key
+feeds:
+  events:
+    description: Event records updated since the previous run.
+    snapshot_mode: incremental
+    natural_key:
+      - event_id
+    cursor:
+      column: updated_at
+    format: json
+schedule:
+  cron: "0 5 * * *"
+  tz: UTC
+entrypoint: src/ingest_events.py
+```
+
+Credentials are symbolic references such as `events_api_key`; never put secret
+values, tokens, connection strings, or environment-specific URLs in a stage
+specification.
+
+## Table and column descriptions
+
+Keep bronze source documentation inline with each feed:
+
+```yaml
+feeds:
+  events:
+    description: Event records updated since the previous run.
+    columns:
+      event_id:
+        description: Identifier assigned by the source system.
+      updated_at:
+        description: Time the source last updated this event.
+```
+
+Each optional `columns` entry requires a `description` string and does not
+accept types or constraints. The source determines bronze columns and types.
+Description edits change specification provenance, not the data contract.
+After deployment, `seq-studio pipeline schema <assetId> -e <env> --json`
+returns descriptions alongside observed columns when supported by the server.
+
+Stage YAML files allow up to 5 MiB; other specification files retain a 1 MiB
+limit. Existing `column_descriptions` and `documentation_ref` declarations
+remain supported; inline `columns.<name>.description` takes precedence.
+
+## Validation coverage
+
+Offline validation checks:
+
+- strict schemas for ingestion, transformation, and serving stages;
+- references between stages, feeds, outputs, and triggers;
+- asset column compatibility and contract changes;
+- symbolic credential and webhook references;
+- deterministic specification and contract hashes; and
+- serving-stage compatibility with declared ORM bindings.
+
+Validation reports all discoverable issues in one pass so repository authors
+can correct the complete graph before deployment.
+
+## Compatibility
+
+- Node.js 20 or newer
+- package versioning follows the release consumed by `seq-studio`
+- the root JavaScript export may change without a standalone public SDK
+  deprecation cycle
+
+This package is distributed under the license declared in `package.json`.

package/dist/authoring/per-table-ingestion.d.ts

@@ -0,0 +1,74 @@
+import type { Criticality, IngestionStageSpec, StageSpecInput } from '../envelope.js';
+import type { FeedFormat, FeedSpec, IngestionRuntime, ScheduleSpec, SnapshotMode } from '../bodies/ingestion.js';
+/** Scalar extraction hints allowed on a feed (matches feedSchema.extraction). */
+export type ExtractionHint = string | number | boolean;
+/**
+ * One source table → one ingestion stage with a single feed. This is the
+ * recommended JH / SilverLake authoring shape (SEQ-2485): N sibling stages
+ * instead of N feeds in one stage.
+ */
+export interface IngestionTableDefinition {
+    /** Source-side table identifier (e.g. iSeries DDMAST). */
+    table: string;
+    /** Override stage slug; default `${stagePrefix}-${tableSlug}`. */
+    stage?: string;
+    /** Override feed name; default is the lowercased table slug. */
+    feed?: string;
+    description?: string;
+    columns?: Readonly<Record<string, {
+        readonly description: string;
+    }>>;
+    column_descriptions?: Readonly<Record<string, string>>;
+    documentation_ref?: string;
+    snapshot_mode: SnapshotMode;
+    natural_key: readonly string[];
+    cursor?: {
+        column: string;
+        encoding?: string;
+    };
+    format?: FeedFormat;
+    pii?: FeedSpec['pii'];
+    extraction?: Readonly<Record<string, ExtractionHint>>;
+}
+/** Shared envelope + runtime config replicated onto every generated stage. */
+export interface PerTableIngestionAuthoring {
+    /** Prefix for generated stage slugs (`silverlake` → `silverlake-ddmast`). */
+    stagePrefix: string;
+    runtime: IngestionRuntime;
+    entrypoint: string;
+    owners: readonly string[];
+    criticality: Criticality;
+    environments: readonly string[];
+    /** Applied to every stage unless overridden per table. */
+    titleTemplate?: string;
+    descriptionTemplate?: string;
+    slos?: IngestionStageSpec['slos'];
+    alerts?: IngestionStageSpec['alerts'];
+    runbook?: string;
+    remediation_posture?: IngestionStageSpec['remediation_posture'];
+    worker?: IngestionStageSpec['worker'];
+    source?: IngestionStageSpec['source'];
+    schedule?: ScheduleSpec;
+    freshness_slo?: string;
+    retention?: string;
+    tables: readonly IngestionTableDefinition[];
+}
+export interface GeneratedStageFile {
+    readonly stage: string;
+    readonly filename: string;
+    readonly spec: StageSpecInput;
+    readonly yaml: string;
+}
+/** Lowercase identifier from a source table name (DDMAST → ddmast). */
+export declare function tableToSlug(table: string): string;
+/** Kebab-case stage slug from prefix + table (`silverlake`, `DDMAST` → `silverlake-ddmast`). */
+export declare function perTableStageSlug(stagePrefix: string, table: string): string;
+/**
+ * Expand a typed authoring definition into one validated-shaped stage spec per
+ * table. Does not run Zod parse — callers should `stageSpecSchema.parse` each
+ * spec (or run `seq-studio pipeline validate` on the emitted directory).
+ */
+export declare function buildPerTableIngestionStages(authoring: PerTableIngestionAuthoring): readonly StageSpecInput[];
+/** Build stage specs and their on-disk filenames (`<stage>.stage.yml`). */
+export declare function generatePerTableStageFiles(authoring: PerTableIngestionAuthoring): readonly GeneratedStageFile[];
+//# sourceMappingURL=per-table-ingestion.d.ts.map

package/dist/authoring/per-table-ingestion.d.ts.map

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

package/dist/authoring/per-table-ingestion.js

@@ -0,0 +1,122 @@
+import { workerCapacityGroup } from '../bodies/ingestion.js';
+import { dumpStageYaml } from './yaml.js';
+const TABLE_SLUG_PATTERN = /[^a-z0-9]+/g;
+/** Lowercase identifier from a source table name (DDMAST → ddmast). */
+export function tableToSlug(table) {
+    const slug = table.trim().toLowerCase().replace(TABLE_SLUG_PATTERN, '_').replace(/^_|_$/g, '');
+    if (!slug)
+        throw new Error(`table '${table}' does not yield a valid slug`);
+    return slug;
+}
+/** Kebab-case stage slug from prefix + table (`silverlake`, `DDMAST` → `silverlake-ddmast`). */
+export function perTableStageSlug(stagePrefix, table) {
+    return `${stagePrefix}-${tableToSlug(table)}`;
+}
+function renderTemplate(template, table, feed) {
+    return template.replace(/\{\{table\}\}/g, table).replace(/\{\{feed\}\}/g, feed);
+}
+function buildFeed(table) {
+    const feedName = table.feed ?? tableToSlug(table.table);
+    const extraction = {
+        table: table.table,
+        ...table.extraction,
+    };
+    const feed = {
+        snapshot_mode: table.snapshot_mode,
+        natural_key: [...table.natural_key],
+        pii: table.pii ?? 'none',
+        format: table.format ?? 'parquet',
+        extraction,
+    };
+    if (table.description)
+        feed.description = table.description;
+    if (table.columns)
+        feed.columns = Object.fromEntries(Object.entries(table.columns).map(([name, column]) => [name, { ...column }]));
+    if (table.column_descriptions)
+        feed.column_descriptions = { ...table.column_descriptions };
+    if (table.documentation_ref)
+        feed.documentation_ref = table.documentation_ref;
+    if (table.cursor)
+        feed.cursor = { ...table.cursor };
+    return { [feedName]: feed };
+}
+/**
+ * The group N sibling stages contend on. Grouping by the shared upstream — the
+ * worker machine + data source for edge workers, the source system for API
+ * pulls — is what keeps ~150 per-table stages from hammering one ODBC
+ * connection or one rate-limited API the moment their crons align. A per-stage
+ * group would be a declaration that they are independent, which they are not.
+ * Falls back to the stage slug only when a stage has no shared upstream to name.
+ */
+function capacityGroup(authoring, stage) {
+    if (authoring.worker)
+        return workerCapacityGroup(authoring.worker);
+    if (authoring.source)
+        return authoring.source.system;
+    return stage.replace(/-/g, '_');
+}
+function buildSchedule(schedule, group) {
+    if (!schedule)
+        return undefined;
+    const policy = schedule.policy;
+    return {
+        ...schedule,
+        // An explicitly authored group always wins — coordinated maintenance
+        // windows and deliberately isolated tables both need the override.
+        policy: policy
+            ? { ...policy, exclusion_group: policy.exclusion_group ?? group }
+            : { singleton: true, exclusion_group: group },
+    };
+}
+/**
+ * Expand a typed authoring definition into one validated-shaped stage spec per
+ * table. Does not run Zod parse — callers should `stageSpecSchema.parse` each
+ * spec (or run `seq-studio pipeline validate` on the emitted directory).
+ */
+export function buildPerTableIngestionStages(authoring) {
+    if (authoring.tables.length === 0) {
+        throw new Error('buildPerTableIngestionStages: tables must be non-empty');
+    }
+    const titleTemplate = authoring.titleTemplate ?? '{{table}} extraction';
+    const descriptionTemplate = authoring.descriptionTemplate ?? 'Ingest {{table}} into bronze via {{feed}}.';
+    return authoring.tables.map((table) => {
+        const stage = table.stage ?? perTableStageSlug(authoring.stagePrefix, table.table);
+        const feedName = table.feed ?? tableToSlug(table.table);
+        return {
+            schema_version: 1,
+            stage,
+            title: renderTemplate(titleTemplate, table.table, feedName),
+            description: renderTemplate(descriptionTemplate, table.table, feedName),
+            type: 'ingestion',
+            owners: [...authoring.owners],
+            criticality: authoring.criticality,
+            ...(authoring.slos ? { slos: authoring.slos } : {}),
+            ...(authoring.alerts ? { alerts: authoring.alerts } : {}),
+            ...(authoring.runbook ? { runbook: authoring.runbook } : {}),
+            ...(authoring.remediation_posture
+                ? { remediation_posture: authoring.remediation_posture }
+                : {}),
+            environments: [...authoring.environments],
+            runtime: authoring.runtime,
+            ...(authoring.worker ? { worker: authoring.worker } : {}),
+            ...(authoring.source ? { source: authoring.source } : {}),
+            feeds: buildFeed(table),
+            ...(authoring.schedule
+                ? { schedule: buildSchedule(authoring.schedule, capacityGroup(authoring, stage)) }
+                : {}),
+            ...(authoring.freshness_slo ? { freshness_slo: authoring.freshness_slo } : {}),
+            ...(authoring.retention ? { retention: authoring.retention } : {}),
+            entrypoint: authoring.entrypoint,
+        };
+    });
+}
+/** Build stage specs and their on-disk filenames (`<stage>.stage.yml`). */
+export function generatePerTableStageFiles(authoring) {
+    return buildPerTableIngestionStages(authoring).map((spec) => ({
+        stage: spec.stage,
+        filename: `${spec.stage}.stage.yml`,
+        spec,
+        yaml: dumpStageYaml(spec),
+    }));
+}
+//# sourceMappingURL=per-table-ingestion.js.map

package/dist/authoring/per-table-ingestion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-table-ingestion.js","sourceRoot":"","sources":["../../src/authoring/per-table-ingestion.ts"],"names":[],"mappings":"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"}

package/dist/authoring/yaml.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Deterministic YAML for generated stage specs — sorted keys, stable quoting.
+ * Same spec object → byte-identical output (golden-friendly).
+ */
+export declare function dumpStageYaml(value: unknown): string;
+//# sourceMappingURL=yaml.d.ts.map

package/dist/authoring/yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../../src/authoring/yaml.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQpD"}

package/dist/authoring/yaml.js

@@ -0,0 +1,15 @@
+import { dump } from 'js-yaml';
+/**
+ * Deterministic YAML for generated stage specs — sorted keys, stable quoting.
+ * Same spec object → byte-identical output (golden-friendly).
+ */
+export function dumpStageYaml(value) {
+    return dump(value, {
+        sortKeys: true,
+        lineWidth: 120,
+        noRefs: true,
+        quotingType: '"',
+        forceQuotes: false,
+    });
+}
+//# sourceMappingURL=yaml.js.map

package/dist/authoring/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../../src/authoring/yaml.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAE9B;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,IAAI,CAAC,KAAK,EAAE;QACjB,QAAQ,EAAE,IAAI;QACd,SAAS,EAAE,GAAG;QACd,MAAM,EAAE,IAAI;QACZ,WAAW,EAAE,GAAG;QAChB,WAAW,EAAE,KAAK;KACnB,CAAC,CAAA;AACJ,CAAC"}

package/dist/binding-gaps.d.ts

@@ -0,0 +1,21 @@
+import type { ResolutionErrorCode } from './errors.js';
+import type { StageSpec } from './envelope.js';
+import { type TargetFactsInput } from './resolve.js';
+export interface BindingGap {
+    readonly code: ResolutionErrorCode;
+    readonly message: string;
+    readonly symbolic?: string;
+    readonly stage?: string;
+}
+/**
+ * Collect target-binding gaps for one portable spec without throwing.
+ * `resolveSpec` remains fail-fast for execute paths; plan aggregates via
+ * {@link collectPipelineBindingGaps}.
+ */
+export declare function collectBindingGaps(spec: StageSpec, facts: TargetFactsInput): BindingGap[];
+/** Aggregate binding gaps across every stage spec in a deploy unit. */
+export declare function collectPipelineBindingGaps({ specs, facts, }: {
+    specs: readonly StageSpec[];
+    facts: TargetFactsInput;
+}): BindingGap[];
+//# sourceMappingURL=binding-gaps.d.ts.map

package/dist/binding-gaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-gaps.d.ts","sourceRoot":"","sources":["../src/binding-gaps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAEvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,GAAG,UAAU,EAAE,CAoEzF;AAED,uEAAuE;AACvE,wBAAgB,0BAA0B,CAAC,EACzC,KAAK,EACL,KAAK,GACN,EAAE;IACD,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IAC3B,KAAK,EAAE,gBAAgB,CAAA;CACxB,GAAG,UAAU,EAAE,CAEf"}

package/dist/binding-gaps.js

@@ -0,0 +1,74 @@
+import { targetFactsSchema } from './resolve.js';
+/**
+ * Collect target-binding gaps for one portable spec without throwing.
+ * `resolveSpec` remains fail-fast for execute paths; plan aggregates via
+ * {@link collectPipelineBindingGaps}.
+ */
+export function collectBindingGaps(spec, facts) {
+    const parsedFacts = targetFactsSchema.safeParse(facts);
+    if (!parsedFacts.success) {
+        return [
+            {
+                code: 'invalid_target_facts',
+                message: `invalid target facts: ${parsedFacts.error.issues
+                    .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                    .join('; ')}`,
+                stage: spec.stage,
+            },
+        ];
+    }
+    const target = parsedFacts.data;
+    if (!spec.environments.includes(target.deploy_target)) {
+        return [
+            {
+                code: 'unknown_target',
+                message: `stage '${spec.stage}' does not declare environment '${target.deploy_target}' (declared: ${spec.environments.join(', ')})`,
+                symbolic: target.deploy_target,
+                stage: spec.stage,
+            },
+        ];
+    }
+    const gaps = [];
+    if (!target.workspace_id) {
+        gaps.push({
+            code: 'missing_workspace_binding',
+            message: `target '${target.deploy_target}' has no workspace binding — every deploy target must bind exactly one workspace_id (no fallback)`,
+            symbolic: target.deploy_target,
+            stage: spec.stage,
+        });
+    }
+    if (spec.type === 'ingestion' && spec.source?.credential) {
+        if (!target.credential_bindings[spec.source.credential]) {
+            gaps.push({
+                code: 'missing_credential_binding',
+                message: `target '${target.deploy_target}' has no credential binding for symbolic name '${spec.source.credential}'`,
+                symbolic: spec.source.credential,
+                stage: spec.stage,
+            });
+        }
+    }
+    if (spec.type === 'serving' && spec.transport?.kind === 'postgres_snapshot_landing_v1') {
+        const binding = target.postgres_snapshot_bindings?.[spec.transport.binding];
+        if (!binding || binding.database !== spec.transport.database)
+            gaps.push({
+                code: 'invalid_target_facts', stage: spec.stage, symbolic: spec.transport.binding,
+                message: `snapshot transport binding '${spec.transport.binding}' is missing or names a different database`,
+            });
+    }
+    for (const channel of spec.alerts?.channels ?? []) {
+        if (!target.alert_channel_bindings[channel]) {
+            gaps.push({
+                code: 'missing_alert_channel_binding',
+                message: `target '${target.deploy_target}' has no alert channel binding for symbolic name '${channel}'`,
+                symbolic: channel,
+                stage: spec.stage,
+            });
+        }
+    }
+    return gaps;
+}
+/** Aggregate binding gaps across every stage spec in a deploy unit. */
+export function collectPipelineBindingGaps({ specs, facts, }) {
+    return specs.flatMap((spec) => collectBindingGaps(spec, facts));
+}
+//# sourceMappingURL=binding-gaps.js.map

package/dist/binding-gaps.js.map

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