@sequenceholdings/pipeline-spec 0.1.0

package/dist/constants.js

@@ -0,0 +1,105 @@
+/**
+ * Stage ids are kebab-case slugs — they become file basenames
+ * (`<stage>.stage.yml`), registry keys, and halves of logical asset ids
+ * (`<stage>.<asset>`), so the grammar is deliberately tight.
+ */
+export const STAGE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** Logical names such as feeds, assets, stages, and namespaces. */
+export const IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
+/** Physical column names may preserve source-system leading underscores. */
+export const COLUMN_IDENTIFIER_PATTERN = /^_?[a-z][a-z0-9_]*$/;
+export const MAX_IDENTIFIER_LENGTH = 63;
+/** Transformation output assets live in the medallion layers or report lane. */
+export const OUTPUT_ASSET_PATTERN = /^(silver|gold|report)\.[a-z][a-z0-9_]*$/;
+/** Raw report passthrough assets are isolated from ontology silver/gold assets. */
+export const REPORT_ASSET_PATTERN = /^report\.[a-z][a-z0-9_]*$/;
+/** ORM-bound serving sources are restricted to the gold layer (mirrors the ORM's `SYNCED_SOURCE_PATTERN`). */
+export const GOLD_ASSET_PATTERN = /^gold\.[a-z][a-z0-9_]*$/;
+/** Serving views are exposed in the Lakebase `public` schema. */
+export const PUBLIC_VIEW_PATTERN = /^public\.[a-z][a-z0-9_]*$/;
+/** FIS compatibility relations are isolated to the dedicated reporting schema. */
+export const REPORTING_TABLE_PATTERN = /^fis_reports\.[a-z][a-z0-9_]*$/;
+/** `<schema>.<table>` reference for Lakebase CDF source tables (e.g. `manual.retail_customers`). */
+export const QUALIFIED_TABLE_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
+/**
+ * Symbolic registry references (credential families, alert channels, worker
+ * machines, source systems). Names only — the tight slug grammar is one of the
+ * two layers that keep literal secrets/URLs out of specs (the other is the
+ * credential scan in the envelope).
+ */
+export const SYMBOLIC_REF_PATTERN = /^[a-z][a-z0-9_-]*$/;
+/** Deploy-target slugs (environment names) — no path separators or dots. */
+export const DEPLOY_TARGET_PATTERN = /^[a-z][a-z0-9_-]*$/;
+/** ISO-8601 duration (`PT4H`, `P1D`, `PT30M`) — used by SLOs, freshness, and retention. */
+export const ISO_DURATION_PATTERN = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
+/** 5–7 whitespace-separated cron fields; semantic validation belongs to the scheduler. */
+export const CRON_PATTERN = /^\S+(\s+\S+){4,6}$/;
+/** IANA timezone shape (`America/New_York`) or `UTC`. */
+export const TIMEZONE_PATTERN = /^(UTC|[A-Za-z]+(?:\/[A-Za-z0-9_+-]+)+)$/;
+/** Stage spec files: `<stage>.stage.yml` in the Pipeline repo root. */
+export const STAGE_FILE_SUFFIXES = ['.stage.yml', '.stage.yaml'];
+/** Named schema artifacts: `schemas/<name>.schema.yml` in the Pipeline repo. */
+export const SCHEMA_FILE_SUFFIXES = ['.schema.yml', '.schema.yaml'];
+/** Directory (relative to the Pipeline root) holding named schema artifacts. */
+export const SCHEMAS_DIRECTORY = 'schemas';
+/** Per-feed documentation sidecars, kept separate from typed schema contracts. */
+export const DOCUMENTATION_FILE_SUFFIXES = ['.documentation.yml', '.documentation.yaml'];
+export const DOCUMENTATION_DIRECTORY = 'documentation';
+/**
+ * Platform-defined operation names. The platform owns these verbs (they get
+ * platform semantics, ledgers, and UI affordances) — author-declared
+ * operations may not shadow them.
+ */
+export const RESERVED_OPERATION_NAMES = new Set([
+    'backfill',
+    'replay',
+    'sample',
+    'live-source-run',
+]);
+/**
+ * Bronze envelope columns the materializer stamps onto every row —
+ * `stamp_envelope`'s `_ENVELOPE_COLUMN_NAMES` in
+ * `databricks/pipeline_runtime/materializer.py` is the single source of
+ * truth this is derived from (not guessed). A SOURCE column sharing one of
+ * these names is silently overwritten by `stamp_envelope` and permanently
+ * lost, so they're reserved for the only column-name-bearing fields an
+ * ingestion feed declares about its own source columns: `natural_key` and
+ * `cursor.column` (`refineFeed` in `bodies/ingestion.ts`).
+ *
+ * Deliberately NOT reserved on transformation `outputs`/CDF `columns`/
+ * serving `projection.columns` (`columnMapSchema` in `columns.ts`) — those
+ * are silver/gold/CDF-envelope business columns on a completely different
+ * write path the materializer never touches, and real specs legitimately
+ * use `ingested_at`/`source_system` there (see
+ * `fixtures/billing/billing-silver.stage.yml`,
+ * `fixtures/er/entity-resolution.stage.yml`).
+ *
+ * MUST match `RESERVED_ENVELOPE_COLUMNS` in
+ * `databricks/pipeline_runtime/materializer.py` byte-for-byte — Python
+ * can't import TS, only a shared naming convention (a parity test on each
+ * side pins the two lists literally equal).
+ */
+export const RESERVED_ENVELOPE_COLUMNS = new Set([
+    'batch_id',
+    'ingested_at',
+    'source_system',
+    'content_hash',
+]);
+/**
+ * Quarantine table name derivation: rows failing a `quarantine`-posture check
+ * land in a platform-derived sibling table. Defined here (M1) so the M6
+ * compiler and every doc derive the same name.
+ */
+export const QUARANTINE_SUFFIX = '__quarantine';
+export const quarantineAssetName = (outputAsset) => `${outputAsset}${QUARANTINE_SUFFIX}`;
+/** Domain-separation prefixes so spec and contract hashes can never collide. */
+export const SPEC_HASH_DOMAIN = 'sequence-pipeline-spec\0';
+export const CONTRACT_HASH_DOMAIN = 'sequence-pipeline-contract\0';
+/**
+ * Per-file byte cap where the loader reads untrusted YAML into memory (same
+ * posture as the ORM loader) — a real failure mode, not a product limit.
+ */
+export const MAX_SPEC_FILE_BYTES = 1024 * 1024;
+/** Stage files may embed full source dictionaries; stay within Git Service's blob cap. */
+export const MAX_STAGE_SPEC_FILE_BYTES = 5 * 1024 * 1024;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,+BAA+B,CAAA;AAE/D,mEAAmE;AACnE,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAA;AAErD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAA;AAE9D,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEvC,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,yCAAyC,CAAA;AAE7E,mFAAmF;AACnF,MAAM,CAAC,MAAM,oBAAoB,GAAG,2BAA2B,CAAA;AAE/D,8GAA8G;AAC9G,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAA;AAE3D,iEAAiE;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,2BAA2B,CAAA;AAE9D,kFAAkF;AAClF,MAAM,CAAC,MAAM,uBAAuB,GAAG,gCAAgC,CAAA;AAEvE,oGAAoG;AACpG,MAAM,CAAC,MAAM,uBAAuB,GAAG,oCAAoC,CAAA;AAE3E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAA;AAExD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,oBAAoB,CAAA;AAEzD,2FAA2F;AAC3F,MAAM,CAAC,MAAM,oBAAoB,GAC/B,qEAAqE,CAAA;AAEvE,0FAA0F;AAC1F,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAA;AAEhD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,yCAAyC,CAAA;AAEzE,uEAAuE;AACvE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,YAAY,EAAE,aAAa,CAAU,CAAA;AAEzE,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,aAAa,EAAE,cAAc,CAAU,CAAA;AAE5E,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAE1C,kFAAkF;AAClF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,oBAAoB,EAAE,qBAAqB,CAAU,CAAA;AACjG,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAA;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAwB,IAAI,GAAG,CAAC;IACnE,UAAU;IACV,QAAQ;IACR,QAAQ;IACR,iBAAiB;CAClB,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAwB,IAAI,GAAG,CAAC;IACpE,UAAU;IACV,aAAa;IACb,eAAe;IACf,cAAc;CACf,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAA;AAE/C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,WAAmB,EAAU,EAAE,CAAC,GAAG,WAAW,GAAG,iBAAiB,EAAE,CAAA;AAExG,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAA0B,CAAA;AAC1D,MAAM,CAAC,MAAM,oBAAoB,GAAG,8BAA8B,CAAA;AAElE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,IAAI,CAAA;AAE9C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA"}

package/dist/diff.d.ts

@@ -0,0 +1,36 @@
+import type { StageSpec } from './envelope.js';
+/**
+ * Contract diffing between two versions of a stage spec — the primitive the
+ * `additive-only` compatibility default enforces. A change is ADDITIVE iff
+ * every consumer requirement satisfied by the old contract is still satisfied
+ * by the new one; anything else is BREAKING. Cosmetic fields (title,
+ * description, owners, runbook) are outside the contract surface entirely.
+ */
+export type ContractClassification = 'breaking' | 'additive' | 'none';
+export declare const CONTRACT_CHANGE_CODES: readonly ["stage_type_changed", "output_added", "output_removed", "column_added", "column_removed", "type_changed", "nullability_loosened", "nullability_tightened", "domain_shrunk", "domain_expanded", "domain_constraint_added", "domain_constraint_removed", "key_changed", "write_pattern_changed", "write_scope_added", "write_scope_changed", "source_changed", "sync_mode_changed", "orm_binding_changed", "satisfies_changed", "primary_key_changed", "feed_added", "feed_removed", "feed_semantics_changed", "violation_posture_changed", "compatibility_mode_changed"];
+export type ContractChangeCode = (typeof CONTRACT_CHANGE_CODES)[number];
+export interface ContractChange {
+    readonly code: ContractChangeCode;
+    readonly column?: string;
+    readonly message: string;
+}
+export interface OutputContractDiff {
+    readonly classification: ContractClassification;
+    readonly changes: readonly ContractChange[];
+}
+export interface ContractDiff {
+    readonly classification: ContractClassification;
+    /** Spec-level (non-output) changes, e.g. a stage kind change. */
+    readonly changes: readonly ContractChange[];
+    /** Per-output classification, keyed by asset name. */
+    readonly outputs: Readonly<Record<string, OutputContractDiff>>;
+}
+/**
+ * Classify the contract delta between two versions of a stage spec.
+ * Transformation outputs diff by asset name; serving projections by exposed
+ * view; non-column contract fields (serving source/sync_mode/orm_binding/
+ * primary_key, ingestion source identity + feed semantics) surface as
+ * spec-level `changes` — everything in `contractSurface` is diffable.
+ */
+export declare function diffContracts(oldSpec: StageSpec, newSpec: StageSpec): ContractDiff;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;;;;;GAMG;AAEH,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;AAErE,eAAO,MAAM,qBAAqB,mjBA2BxB,CAAA;AAEV,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAA;AAUvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,cAAc,EAAE,sBAAsB,CAAA;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CAC5C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,cAAc,EAAE,sBAAsB,CAAA;IAC/C,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;IAC3C,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAA;CAC/D;AAsMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,GAAG,YAAY,CA8ElF"}

package/dist/diff.js

@@ -0,0 +1,300 @@
+import { requireResolvedColumns } from './columns.js';
+import { domainKey } from './compatibility.js';
+import { feedContract, ingestionSourceIdentity } from './bodies/ingestion.js';
+import { canonicalJson } from './hash.js';
+export const CONTRACT_CHANGE_CODES = [
+    'stage_type_changed',
+    'output_added',
+    'output_removed',
+    'column_added',
+    'column_removed',
+    'type_changed',
+    'nullability_loosened',
+    'nullability_tightened',
+    'domain_shrunk',
+    'domain_expanded',
+    'domain_constraint_added',
+    'domain_constraint_removed',
+    'key_changed',
+    'write_pattern_changed',
+    'write_scope_added',
+    'write_scope_changed',
+    'source_changed',
+    'sync_mode_changed',
+    'orm_binding_changed',
+    'satisfies_changed',
+    'primary_key_changed',
+    'feed_added',
+    'feed_removed',
+    'feed_semantics_changed',
+    'violation_posture_changed',
+    'compatibility_mode_changed',
+];
+const ADDITIVE_CODES = new Set([
+    'output_added',
+    'column_added',
+    'nullability_tightened',
+    'feed_added',
+    'write_scope_added',
+]);
+function classify(changes) {
+    if (changes.length === 0)
+        return 'none';
+    return changes.every((change) => ADDITIVE_CODES.has(change.code)) ? 'additive' : 'breaking';
+}
+function diffColumnMaps(oldColumns, newColumns) {
+    const changes = [];
+    for (const [name, oldColumn] of Object.entries(oldColumns)) {
+        const newColumn = newColumns[name];
+        if (!newColumn) {
+            changes.push({ code: 'column_removed', column: name, message: `column '${name}' was removed` });
+            continue;
+        }
+        if (oldColumn.type !== newColumn.type) {
+            changes.push({
+                code: 'type_changed',
+                column: name,
+                message: `column '${name}' changed type '${oldColumn.type}' → '${newColumn.type}'`,
+            });
+        }
+        if (oldColumn.nullable !== newColumn.nullable) {
+            changes.push(newColumn.nullable
+                ? {
+                    code: 'nullability_loosened',
+                    column: name,
+                    message: `column '${name}' became nullable — consumers requiring non-null break`,
+                }
+                : { code: 'nullability_tightened', column: name, message: `column '${name}' became non-null` });
+        }
+        if (oldColumn.key !== newColumn.key) {
+            changes.push({ code: 'key_changed', column: name, message: `column '${name}' key participation changed` });
+        }
+        if (oldColumn.on_violation !== newColumn.on_violation) {
+            // Rows move between fail/quarantine/warn destinations — output
+            // semantics change for every consumer, so never additive.
+            changes.push({
+                code: 'violation_posture_changed',
+                column: name,
+                message: `column '${name}' on_violation changed '${oldColumn.on_violation}' → '${newColumn.on_violation}'`,
+            });
+        }
+        const oldDomain = oldColumn.domain;
+        const newDomain = newColumn.domain;
+        if (oldDomain && !newDomain) {
+            changes.push({
+                code: 'domain_constraint_removed',
+                column: name,
+                message: `column '${name}' dropped its domain constraint — new values may appear`,
+            });
+        }
+        else if (!oldDomain && newDomain) {
+            changes.push({
+                code: 'domain_constraint_added',
+                column: name,
+                message: `column '${name}' gained a domain constraint — previously legal values may vanish`,
+            });
+        }
+        else if (oldDomain && newDomain) {
+            const newKeys = new Set(newDomain.map(domainKey));
+            const removed = oldDomain.filter((value) => !newKeys.has(domainKey(value)));
+            const oldKeys = new Set(oldDomain.map(domainKey));
+            const added = newDomain.filter((value) => !oldKeys.has(domainKey(value)));
+            if (removed.length > 0) {
+                changes.push({
+                    code: 'domain_shrunk',
+                    column: name,
+                    message: `column '${name}' domain shrank (removed: ${removed.map(String).join(', ')}) — consumers relying on those values break`,
+                });
+            }
+            if (added.length > 0) {
+                changes.push({
+                    code: 'domain_expanded',
+                    column: name,
+                    message: `column '${name}' domain expanded (added: ${added.map(String).join(', ')}) — consumers with closed handling break`,
+                });
+            }
+        }
+    }
+    for (const name of Object.keys(newColumns)) {
+        if (!(name in oldColumns)) {
+            changes.push({ code: 'column_added', column: name, message: `column '${name}' was added` });
+        }
+    }
+    return changes;
+}
+function contractsOf(spec) {
+    if (spec.type === 'transformation') {
+        const contracts = {};
+        for (const [asset, output] of Object.entries(spec.outputs)) {
+            contracts[asset] = {
+                columns: requireResolvedColumns(output.columns, `${spec.stage}: outputs.${asset}.columns`),
+                write_pattern: output.write_pattern,
+                ...(output.write_scope ? { write_scope: output.write_scope } : {}),
+                on_type_violation: output.on_type_violation,
+                compatibility: output.compatibility,
+            };
+        }
+        return contracts;
+    }
+    if (spec.type === 'serving') {
+        return {
+            [spec.expose.view]: {
+                columns: requireResolvedColumns(spec.projection.columns, `${spec.stage}: projection.columns`),
+            },
+        };
+    }
+    return {};
+}
+/**
+ * Non-column contract fields — everything `contractSurface` covers beyond
+ * output/projection columns must be diffable here, or additive-only
+ * enforcement would miss breaking changes that DO churn `contract_hash`:
+ * serving source/sync_mode/orm_binding/primary_key, and ingestion source
+ * identity + feed batch semantics.
+ */
+function specLevelChanges(oldSpec, newSpec) {
+    const changes = [];
+    if (oldSpec.type === 'serving' && newSpec.type === 'serving') {
+        if (canonicalJson(oldSpec.source) !== canonicalJson(newSpec.source)) {
+            changes.push({
+                code: 'source_changed',
+                message: `serving source changed '${oldSpec.source.stage}.${oldSpec.source.output}' → '${newSpec.source.stage}.${newSpec.source.output}'`,
+            });
+        }
+        if (oldSpec.sync_mode !== newSpec.sync_mode) {
+            changes.push({
+                code: 'sync_mode_changed',
+                message: `sync_mode changed '${oldSpec.sync_mode}' → '${newSpec.sync_mode}'`,
+            });
+        }
+        if (canonicalJson(oldSpec.orm_binding ?? null) !== canonicalJson(newSpec.orm_binding ?? null)) {
+            changes.push({
+                code: 'orm_binding_changed',
+                message: 'orm_binding changed — the platform↔ORM join key is contract identity',
+            });
+        }
+        if (canonicalJson(oldSpec.satisfies ?? null) !== canonicalJson(newSpec.satisfies ?? null)) {
+            changes.push({
+                code: 'satisfies_changed',
+                message: 'satisfies changed — the ORM contract pin (namespace.table@hash) is contract identity',
+            });
+        }
+        if (canonicalJson(oldSpec.projection.primary_key) !== canonicalJson(newSpec.projection.primary_key)) {
+            changes.push({
+                code: 'primary_key_changed',
+                message: `primary_key changed [${oldSpec.projection.primary_key.join(', ')}] → [${newSpec.projection.primary_key.join(', ')}]`,
+            });
+        }
+    }
+    if (oldSpec.type === 'ingestion' && newSpec.type === 'ingestion') {
+        const oldSource = ingestionSourceIdentity(oldSpec);
+        const newSource = ingestionSourceIdentity(newSpec);
+        if (oldSource !== newSource) {
+            changes.push({
+                code: 'source_changed',
+                message: `source identity changed '${oldSource}' → '${newSource}' — every derived bronze name moves`,
+            });
+        }
+        for (const [name, oldFeed] of Object.entries(oldSpec.feeds)) {
+            const newFeed = newSpec.feeds[name];
+            if (!newFeed) {
+                changes.push({ code: 'feed_removed', message: `feed '${name}' was removed` });
+                continue;
+            }
+            if (canonicalJson(feedContract(oldFeed)) !== canonicalJson(feedContract(newFeed))) {
+                changes.push({
+                    code: 'feed_semantics_changed',
+                    message: `feed '${name}' batch semantics changed (snapshot_mode/keys/cursor/format/pii/extraction)`,
+                });
+            }
+        }
+        for (const name of Object.keys(newSpec.feeds)) {
+            if (!(name in oldSpec.feeds)) {
+                changes.push({ code: 'feed_added', message: `feed '${name}' was added` });
+            }
+        }
+    }
+    return changes;
+}
+/**
+ * Classify the contract delta between two versions of a stage spec.
+ * Transformation outputs diff by asset name; serving projections by exposed
+ * view; non-column contract fields (serving source/sync_mode/orm_binding/
+ * primary_key, ingestion source identity + feed semantics) surface as
+ * spec-level `changes` — everything in `contractSurface` is diffable.
+ */
+export function diffContracts(oldSpec, newSpec) {
+    if (oldSpec.type !== newSpec.type) {
+        // A stage kind change is a lifecycle-breaking replacement even when the
+        // derived output maps happen to overlap (e.g. ingestion → transformation
+        // both derive empty/none) — never classifiable as additive.
+        return {
+            classification: 'breaking',
+            changes: [
+                {
+                    code: 'stage_type_changed',
+                    message: `stage kind changed '${oldSpec.type}' → '${newSpec.type}' — a replacement, not an evolution`,
+                },
+            ],
+            outputs: {},
+        };
+    }
+    const oldContracts = contractsOf(oldSpec);
+    const newContracts = contractsOf(newSpec);
+    const outputs = {};
+    for (const [asset, oldContract] of Object.entries(oldContracts)) {
+        const newContract = newContracts[asset];
+        if (!newContract) {
+            outputs[asset] = {
+                classification: 'breaking',
+                changes: [{ code: 'output_removed', message: `output '${asset}' was removed` }],
+            };
+            continue;
+        }
+        const changes = diffColumnMaps(oldContract.columns, newContract.columns);
+        if (canonicalJson(oldContract.write_scope) !== canonicalJson(newContract.write_scope)) {
+            changes.push({
+                code: oldContract.write_scope ? 'write_scope_changed' : 'write_scope_added',
+                message: `output '${asset}' write scope changed ${canonicalJson(oldContract.write_scope) ?? 'unscoped'} → ${canonicalJson(newContract.write_scope) ?? 'unscoped'}`,
+            });
+        }
+        // Non-column output posture fields — every one of them is hashed by
+        // contractSurface, so every one must be diffable (never silently `none`).
+        const postureFields = [
+            ['write_pattern', 'write_pattern_changed'],
+            ['on_type_violation', 'violation_posture_changed'],
+            ['compatibility', 'compatibility_mode_changed'],
+        ];
+        for (const [field, code] of postureFields) {
+            const oldValue = oldContract[field];
+            const newValue = newContract[field];
+            if (oldValue !== undefined && newValue !== undefined && oldValue !== newValue) {
+                changes.push({
+                    code,
+                    message: `output '${asset}' ${field} changed '${oldValue}' → '${newValue}'`,
+                });
+            }
+        }
+        outputs[asset] = { classification: classify(changes), changes };
+    }
+    for (const asset of Object.keys(newContracts)) {
+        if (!(asset in oldContracts)) {
+            outputs[asset] = {
+                classification: 'additive',
+                changes: [{ code: 'output_added', message: `output '${asset}' was added` }],
+            };
+        }
+    }
+    const specChanges = specLevelChanges(oldSpec, newSpec);
+    const classifications = [
+        ...Object.values(outputs).map((output) => output.classification),
+        classify(specChanges),
+    ];
+    const overall = classifications.includes('breaking')
+        ? 'breaking'
+        : classifications.includes('additive')
+            ? 'additive'
+            : 'none';
+    return { classification: overall, changes: specChanges, outputs };
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

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

package/dist/documentation.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { StageSpec } from './envelope.js';
+export declare const columnDescriptionsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/** Bronze column annotations do not declare or enforce types from the source. */
+export declare const feedColumnsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    description: z.ZodString;
+}, z.core.$strict>>;
+/** Documentation is deliberately independent of enforced column/type contracts. */
+export declare const feedDocumentationSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    column_descriptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type FeedDocumentation = z.infer<typeof feedDocumentationSchema>;
+/** Resolve sidecars into the stage snapshot; explicitly authored metadata wins. */
+export declare function resolveFeedDocumentation({ spec, file, documentation, }: {
+    spec: StageSpec;
+    file: string;
+    documentation: ReadonlyMap<string, FeedDocumentation>;
+}): void;
+/** Direct resolver callers must load documentation before creating immutable snapshots. */
+export declare function assertFeedDocumentationResolved(spec: StageSpec): void;
+//# sourceMappingURL=documentation.d.ts.map

package/dist/documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.d.ts","sourceRoot":"","sources":["../src/documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAI9C,eAAO,MAAM,wBAAwB,uCAAiD,CAAA;AAEtF,iFAAiF;AACjF,eAAO,MAAM,iBAAiB;;mBAG7B,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,uBAAuB;;;kBAGlC,CAAA;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE,mFAAmF;AACnF,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,IAAI,EACJ,aAAa,GACd,EAAE;IACD,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CACtD,GAAG,IAAI,CAkBP;AAED,2FAA2F;AAC3F,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAWrE"}

package/dist/documentation.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { MAX_IDENTIFIER_LENGTH } from './constants.js';
+import { SpecDefinitionError } from './errors.js';
+/** Literal physical names, including source-native characters such as '#'. */
+const physicalColumnNameSchema = z.string().min(1).max(MAX_IDENTIFIER_LENGTH);
+export const columnDescriptionsSchema = z.record(physicalColumnNameSchema, z.string());
+/** Bronze column annotations do not declare or enforce types from the source. */
+export const feedColumnsSchema = z.record(physicalColumnNameSchema, z.strictObject({ description: z.string() }));
+/** Documentation is deliberately independent of enforced column/type contracts. */
+export const feedDocumentationSchema = z.strictObject({
+    description: z.string().optional(),
+    column_descriptions: columnDescriptionsSchema.optional(),
+});
+/** Resolve sidecars into the stage snapshot; explicitly authored metadata wins. */
+export function resolveFeedDocumentation({ spec, file, documentation, }) {
+    if (spec.type !== 'ingestion')
+        return;
+    for (const [name, feed] of Object.entries(spec.feeds)) {
+        if (feed.documentation_ref === undefined)
+            continue;
+        const docs = documentation.get(feed.documentation_ref);
+        if (!docs) {
+            throw new SpecDefinitionError(`documentation_ref '${feed.documentation_ref}' does not resolve — no documentation/${feed.documentation_ref}.documentation.yml in this Pipeline`, file, `feeds.${name}.documentation_ref`);
+        }
+        if (feed.description === undefined && docs.description !== undefined)
+            feed.description = docs.description;
+        if (docs.column_descriptions !== undefined) {
+            feed.column_descriptions = { ...docs.column_descriptions, ...feed.column_descriptions };
+        }
+        delete feed.documentation_ref;
+    }
+}
+/** Direct resolver callers must load documentation before creating immutable snapshots. */
+export function assertFeedDocumentationResolved(spec) {
+    if (spec.type !== 'ingestion')
+        return;
+    for (const [name, feed] of Object.entries(spec.feeds)) {
+        if (feed.documentation_ref !== undefined) {
+            throw new SpecDefinitionError(`unresolved documentation_ref '${feed.documentation_ref}' — load specs through parseSpecSources/loadSpecDirectory first`, undefined, `feeds.${name}.documentation_ref`);
+        }
+    }
+}
+//# sourceMappingURL=documentation.js.map

package/dist/documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.js","sourceRoot":"","sources":["../src/documentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGjD,8EAA8E;AAC9E,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAA;AAC7E,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,wBAAwB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;AAEtF,iFAAiF;AACjF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CACvC,wBAAwB,EACxB,CAAC,CAAC,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAC5C,CAAA;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,YAAY,CAAC;IACpD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,mBAAmB,EAAE,wBAAwB,CAAC,QAAQ,EAAE;CACzD,CAAC,CAAA;AAIF,mFAAmF;AACnF,MAAM,UAAU,wBAAwB,CAAC,EACvC,IAAI,EACJ,IAAI,EACJ,aAAa,GAKd;IACC,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;QAAE,OAAM;IACrC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS;YAAE,SAAQ;QAClD,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;QACtD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,mBAAmB,CAC3B,sBAAsB,IAAI,CAAC,iBAAiB,yCAAyC,IAAI,CAAC,iBAAiB,qCAAqC,EAChJ,IAAI,EACJ,SAAS,IAAI,oBAAoB,CAClC,CAAA;QACH,CAAC;QACD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;QACzG,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC3C,IAAI,CAAC,mBAAmB,GAAG,EAAE,GAAG,IAAI,CAAC,mBAAmB,EAAE,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAA;QACzF,CAAC;QACD,OAAO,IAAI,CAAC,iBAAiB,CAAA;IAC/B,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,+BAA+B,CAAC,IAAe;IAC7D,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;QAAE,OAAM;IACrC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACzC,MAAM,IAAI,mBAAmB,CAC3B,iCAAiC,IAAI,CAAC,iBAAiB,iEAAiE,EACxH,SAAS,EACT,SAAS,IAAI,oBAAoB,CAClC,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC"}