---
phase: 11.1-review-possible-ddl-and-query-syntax-options-and-bring-it-as-close-as-we-can-to-snowflake-semantic-views
plan: "01"
subsystem: database
tags: [rust, serde, model, semantic-views, duckdb]

requires:
  - phase: 11-scalar-function-ddl
    provides: "SemanticViewDefinition, Join, Dimension, Metric model types"

provides:
  - "DESIGN.md with before/after DDL and query syntax reference"
  - "TableRef struct: alias-to-table mapping for the tables DDL parameter"
  - "JoinColumn struct: from/to column pair for join relationships"
  - "Join.join_columns field: Vec<JoinColumn> with serde default"
  - "SemanticViewDefinition.tables field: Vec<TableRef> with serde default"

affects:
  - "11.1-02 (parse_args.rs uses TableRef, JoinColumn, SemanticViewDefinition)"
  - "11.1-03 (expand.rs uses Join.join_columns for SQL codegen)"

tech-stack:
  added: []
  patterns:
    - "serde default on new fields for backward compat with stored JSON"
    - "cfg_attr(feature = arbitrary) on new structs for proptest support"

key-files:
  created:
    - ".planning/phases/11.1-.../DESIGN.md"
  modified:
    - "src/model.rs"
    - "src/expand.rs"
    - "tests/expand_proptest.rs"

key-decisions:
  - "TableRef and JoinColumn both derive Default to make struct construction ergonomic"
  - "Join.join_columns placed after from_cols to maintain field order consistency"
  - "SemanticViewDefinition.tables placed after base_table (before dimensions) for logical grouping"
  - "All new fields use #[serde(default)] — required for backward compat with stored JSON"

patterns-established:
  - "New model fields always added with serde default — never break existing stored definitions"

requirements-completed:
  - DDL-03
  - DDL-04

duration: 12min
completed: 2026-03-02
---

# Phase 11.1 Plan 01: Data Model Contracts + DESIGN.md Summary

**DESIGN.md canonical before/after syntax reference + TableRef/JoinColumn model types added to model.rs with serde backward compat**

## Performance

- **Duration:** 12 min
- **Started:** 2026-03-02T00:00:00Z
- **Completed:** 2026-03-02T00:12:00Z
- **Tasks:** 2
- **Files modified:** 4

## Accomplishments
- Created DESIGN.md documenting the complete before/after DDL and query syntax transformation for Phase 11.1
- Added `TableRef` struct (alias + table) and `JoinColumn` struct (from + to) to model.rs with serde derive
- Extended `Join` with `join_columns: Vec<JoinColumn>` and `SemanticViewDefinition` with `tables: Vec<TableRef>`, both with `#[serde(default)]` for backward compat
- Added 6 unit tests in `phase11_1_model_tests` covering serde roundtrips and backward compat
- All 85 tests continue to pass (78 unit + 6 proptest + 1 doctest)

## Task Commits

Each task was committed atomically:

1. **Task 1: Write DESIGN.md** - `bf8e651` (docs)
2. **Task 2: Add TableRef, JoinColumn to model.rs; fix expand.rs/proptest** - `1db13ab` (feat)

## Files Created/Modified
- `.planning/phases/11.1-.../DESIGN.md` - Complete before/after syntax reference for all downstream plans
- `src/model.rs` - Added TableRef, JoinColumn structs; extended Join + SemanticViewDefinition; 6 new tests
- `src/expand.rs` - Added `tables: vec![]` and `join_columns: vec![]` to all struct initializers (Rule 3 fix)
- `tests/expand_proptest.rs` - Same struct initializer fixes for proptest fixtures

## Decisions Made
- `TableRef` and `JoinColumn` both derive `Default` for ergonomic construction
- New fields use `#[serde(default)]` — required for backward compat with stored JSON
- `tables` placed after `base_table` in `SemanticViewDefinition` for logical grouping

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Added tables/join_columns fields to expand.rs and expand_proptest.rs struct initializers**
- **Found during:** Task 2 (cargo test after model.rs changes)
- **Issue:** Rust requires all struct fields in initializers; existing tests in expand.rs and expand_proptest.rs use `SemanticViewDefinition {}` and `Join {}` literals that became incomplete after new fields were added
- **Fix:** Used Python script to add `tables: vec![]` to all 16 `SemanticViewDefinition` initializers in expand.rs and both in expand_proptest.rs; added `join_columns: vec![]` to all 10 `Join` initializers in expand.rs and 2 in expand_proptest.rs
- **Files modified:** src/expand.rs, tests/expand_proptest.rs
- **Verification:** `cargo test` passes — 85 tests all green
- **Committed in:** 1db13ab (part of task 2 commit)

---

**Total deviations:** 1 auto-fixed (1 blocking)
**Impact on plan:** Necessary fix; all existing tests preserved. No scope creep.

## Issues Encountered
None

## Next Phase Readiness
- DESIGN.md available for all downstream plans as canonical before/after reference
- `TableRef`, `JoinColumn`, `Join.join_columns`, `SemanticViewDefinition.tables` available for Plan 02 (parse_args.rs) and Plan 03 (expand.rs codegen)
- All tests green — clean baseline for Wave 2

---
*Phase: 11.1-review-possible-ddl-and-query-syntax-options-and-bring-it-as-close-as-we-can-to-snowflake-semantic-views*
*Completed: 2026-03-02*
