Support MATERIALIZED, ALIAS, and EPHEMERAL columns

[KeKs0r]

Add first-class MATERIALIZED, ALIAS, and EPHEMERAL column definitions in TypeScript and Python. A derived column such as Date MATERIALIZED toDate(Datetime) can now be declared with defaultKind / default_kind and default: 'fn:…', survive pull/reload, and participate in drift detection.

Closes #206.

Behavior

• Preserve expression kinds through SQL, introspection, pull, and snapshots. Omitted kind and explicit DEFAULT remain equivalent; bare EPHEMERAL is supported.
• Compare expression tokens without losing whitespace or escapes inside literals. Distinguish literal strings from SQL expressions, ignore insignificant formatting/comments, and correctly escape literal backslashes. Fix Python pull marking introspected expressions as literals.
• Generate Row for default SELECT *, RowExplicit for all readable columns, and RowInsert for writes. Emit corresponding Zod/Pydantic models and use insert models in TypeScript ingest helpers.
• Check live target column metadata during backfill planning and local execution, including when local schema loading fails. Block unavailable/unknown metadata and targets with unrecoverable EPHEMERAL inputs. Omit generated columns from MV replay projections.
• Emit explicit removal of stored expressions. Warn in human/JSON output and migration SQL that expression changes do not rewrite stored historical values. Never automatically issue MATERIALIZE COLUMN.
• Reject automatic storage-kind conversions involving ALIAS or EPHEMERAL, without silently dropping and recreating columns.

Scope and limitations

Snapshot adoption after manual conversions is outside this PR. There is no new reconciliation command or supported end-to-end workflow for those conversions; the generator rejects them. That workflow needs a separate design.

Historical data rewrites remain explicit and cannot recover discarded ephemeral inputs. Token comparison is structural, not a proof of algebraic equivalence between arbitrary SQL expressions.

Validation

• 85 targeted TypeScript tests passed, covering column expressions, live ClickHouse 26.3 lifecycle/model validation, backfill planning, generation, empty migrations, and table scoping.
• 1,275 Python unit tests passed. Targeted live lifecycle and migration-generation suites: 14 passed, one existing environment-gated check skipped.
• All 24 affected TypeScript typecheck, lint, and build tasks passed.
• Python strict Mypy passed for all 137 source files; Ruff passed for source and expression tests.
• Both CLIs' generate --help confirm no reconciliation option. Documentation build passed (55 pages); git diff --check passed.
• Column lifecycle tests are included in the ClickHouse 26.3/26.8 CI matrix.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-27T02:03:53.851188Z	c2f1db4	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.