rdbms-playground/docs/plans/20260524-adr-0035-sql-ddl-4a.md

Plan: ADR-0035 Phase 4, sub-phase 4a — dispatch + CREATE TABLE core

This is the first slice of ADR-0035 (advanced-mode SQL DDL). It lands advanced-mode create dispatch and a structurally-executed SqlCreateTable command for the column/constraint/PK core — no foreign keys (those are 4b). It mirrors the ADR-0033 DML sub-phase model (tests/sql_insert.rs et al.) and reuses the existing low-level create-table machinery per ADR-0035 §1.

1. Baseline

• Tests: 1698 passing, 0 failing, 0 skipped, 1 ignored (the long-standing friendly/mod.rs ```ignore doctest). Clippy clean (cargo clippy --all-targets -- -D warnings).
• Branch main; last commit 19d3cd3 (the ADR-0035 /runda refinements). Re-confirmed green at the start of this work.

2. Decisions locked with the user (do not re-litigate)

From the ADR-0035 design (handoff 36 §3) and the pre-implementation /runda round (2026-05-24), all user-confirmed:

1. Own command, structural execution. SqlCreateTable is its own Command / Request variant (not a reuse of Command::CreateTable). It executes structurally by reusing the low-level helper do_create_table — not verbatim SQL. Simple mode is untouched.
2. IF NOT EXISTS is admitted as a no-op that succeeds with a note ("table already exists — skipped"), not a parse error and not the plain-form "already exists" error. (ADR §3/§4/§12/§13.)
3. INTEGER PRIMARY KEY → plain int PK. The type map is purely lexical; auto-increment is reachable only via the explicit serial type. (ADR §3.)
4. Dispatch: create is a shared entry word — it stays CommandCategory::Simple for ddl::CREATE and gains an Advanced entry for the new SQL node, exactly as insert/update/ delete do (ADR-0033 Amendment 1: SQL-first in advanced, simple fallback).
5. Type vocabulary: the ten playground keywords and the standard-SQL aliases (integer/smallint/bigint→int, varchar/char→text, boolean→bool, timestamp→datetime, numeric→decimal, float/double precision→real, binary/varbinary→blob); a length/precision argument (varchar(255)) is accepted and ignored.
6. Undo: SqlCreateTable is a user mutation carrying a source, wrapped in snapshot_then like the existing 19 mutating arms → one undo step. create needs no is_app_lifecycle_entry_word change (it's a write).

3. Phase 1 — Requirements checklist (4a scope)

Functional

• CREATE TABLE <name> ( <col-elements>, [table-PK] ) parses in advanced mode and produces Command::SqlCreateTable.
• Simple-mode create table T with pk … is unchanged and still parses as Command::CreateTable (dispatch fallback verified).
• Column element: <name> <type> [constraints…] where constraints are NOT NULL, UNIQUE, PRIMARY KEY, DEFAULT <expr>, CHECK (<expr>) — the per-column ADR-0029 set spelled in SQL.
• Type slot: ten keywords + the §2.5 alias map; length/precision arg accepted-and-ignored.
• INTEGER PRIMARY KEY → plain int PK (no auto-increment).
• Table-level PRIMARY KEY (<col>, …) — single and compound.
• Single-column table-level UNIQUE(a) / CHECK(expr-over-a) accepted by normalizing into the column spec; composite UNIQUE(a,b) / multi-column table CHECK rejected "not yet supported" (→ 4a.2, §6).
• IF NOT EXISTS → no-op-with-note on an existing table.
• Structural execution: reuses do_create_table; the new object is a first-class playground table — __rdbms_playground_columns populated with the playground user_type, STRICT applied, CSV layer
  • project.yaml correct (ADR-0015 §6 ordering preserved).
• One undo step per CREATE TABLE; undo removes the table + metadata; redo recreates it.
• Errors route through the friendly layer, engine-neutral wording (unknown type; duplicate column name; the IF NOT EXISTS note).

Cross-cutting / integration

• history.log records the literal submitted SQL line; replay re-runs it as a write (no replay-filter change — ADR §10).
• Ambient assistance comes free from the walker: highlighting, [ERR]/[WRN], usage skeleton, completion. The node authors IdentSource::NewName on the table-name slot, IdentSource::Types on the type slot, its help_id/usage_ids, and the 4a DDL diagnostics.

Documentation

• On 4a end-to-end validation, flip ADR-0035 status Proposed → Accepted (the ADR-0033 lifecycle) and update docs/adr/README.md in the same edit.
• requirements.md: Q4 progresses (DDL create landing); do not mark C1 [x] (rename is 4h, advanced-only).

Testing (ADR-0008 four tiers)

• Tier 1 (unit, in-crate): type-alias map; the ast_builder for valid/invalid CREATE TABLE shapes; column-constraint parsing; compound PK; INTEGER PRIMARY KEY→int; IF NOT EXISTS flag captured.
• Tier 2 (insta): structure-view snapshot after a SQL create, if it adds signal over existing create-table snapshots (mirror the existing simple-mode create snapshot; skip if redundant).
• Tier 3 (tests/sql_create_table.rs, mirror tests/sql_insert.rs): full-stack parse→dispatch→worker; assert metadata rows, CSV/yaml, describe output; alias mapping; IF NOT EXISTS no-op-with-note; plain-form duplicate error; simple-mode create still works in advanced mode (fallback).
• Undo Tier 3 (in tests/undo_snapshots.rs or a sibling): CREATE TABLE is one undo step; undo drops the table + clears its metadata; redo recreates it identically.

4. Architecture & design

4.1 New grammar node — src/dsl/grammar/sql_create_table.rs

Mirror src/dsl/grammar/sql_insert.rs:

• CommandNode SQL_CREATE_TABLE with entry: Word::keyword("create"), a CREATE_TABLE shape, ast_builder: build_sql_create_table, help_id: Some("ddl.sql_create_table"), usage_ids: &["parse.usage.sql_create_table"].
• Table-name slot: IdentSource::NewName, role "table_name", writes_table: false (the table doesn't exist yet), plus the internal-__rdbms_* / validate_user_name rejection used elsewhere.
• After table keyword: an optional IF NOT EXISTS keyword run that sets a flag in the builder.
• Column list: a Repeated of column-or-table elements inside ( … ).
  • Column element: name slot (IdentSource::NewName) + type slot (IdentSource::Types) + a constraint walk. The type slot consumes an optional parenthesised number/number-pair and discards it (length/precision ignored).
  • Table element (4a): PRIMARY KEY ( col, … ). No FOREIGN KEY, no inline REFERENCES in 4a (those parse-error for now; 4b adds them).
• CHECK (<expr>) / DEFAULT <expr> reuse the ADR-0031 fragment via Node::Subgrammar(&sql_expr::SQL_OR_EXPR) (the same mechanism sql_insert.rs uses for value expressions). The matched expression is compiled to storable SQL via the existing compile_check_sql path used by do_create_table.

Register in REGISTRY (src/dsl/grammar/mod.rs, Advanced group): (&data::SQL_CREATE_TABLE, CommandCategory::Advanced) alongside the existing (&ddl::CREATE, CommandCategory::Simple). The category-grouped dispatcher then tries SQL-first in advanced mode and falls back to the simple create table … with pk … node when the SQL shape doesn't match — identical to the insert precedent. (Confirm the exact re-export path: simple CREATE is ddl::CREATE; place the new node so it's reachable as the registry expects, mirroring how SQL_INSERT is wired.)

4.2 Command AST — src/dsl/command.rs

New variant (4a shape; 4b will extend it with FK/relationship specs):

SqlCreateTable {
    name: String,
    columns: Vec<ColumnSpec>,     // reuse the existing ColumnSpec
    primary_key: Vec<String>,     // single or compound, table- or column-level
    if_not_exists: bool,
}

ColumnSpec (name, ty: Type, not_null, unique, default: Option<Value>, check: Option<Expr>) is reused unchanged — the SQL and simple paths build the same spec. Column-level PRIMARY KEY and table-level PRIMARY KEY (…) both normalise into primary_key.

4.3 Worker — src/db.rs

• New Request::SqlCreateTable { name, columns, primary_key, if_not_exists, source: Option<String>, reply }.
• Dispatch arm wraps in snapshot_then(snap, batch, conn, source.as_deref(), reply, || …) exactly like the CreateTable arm.
• The closure:
  • If if_not_exists and the table already exists → no-op: return a success outcome that the runtime renders as a note rather than a structure refresh. (See 4.4.)
  • Else → call the existing do_create_table(conn, persistence, source, &name, &columns, &primary_key); structural execution, metadata, CSV, STRICT all come from the shared helper.
• handle_request's exhaustive match forces handling the new variant — it must be wrapped, never reply.send-ed raw (the handoff must-not-forget).
• No is_app_lifecycle_entry_word change: create is a write.

4.4 The IF NOT EXISTS no-op-with-note outcome

do_create_table returns TableDescription. For the skip path we need the runtime to show a note instead of (or alongside) a structure. Two candidate mechanisms — pick one, escalate if non-obvious:

• (a) Worker reply is an enum CreateOutcome { Created(TableDescription), Skipped(TableDescription) }; the runtime emits the engine-neutral note on Skipped and the structure on Created.
• (b) Reply stays TableDescription and carries an optional note: Option<NoteKey> the runtime renders.

Decided: mechanism (a) (§6.2) — explicit and reused by DROP TABLE IF EXISTS (4c). This touches the worker reply type and the runtime/event rendering; the one piece of 4a that adds plumbing beyond "mirror SqlInsert".

4.5 Type-alias map — src/dsl/types.rs

No alias map exists today (Type: FromStr covers only the ten canonical names). Add a single resolver, e.g. fn resolve_type_name(raw: &str) -> Option<Type> that lowercases, maps the §2.5 aliases onto the canonical Type, and falls through to the canonical FromStr. The grammar's type slot calls this; an unrecognised name yields the engine-neutral diagnostic/error "unknown type". Length/precision is stripped by the grammar before the name reaches the resolver.

4.6 Friendly catalog + keys — lockstep

For every new key, add a body to src/friendly/strings/en-US.yaml and an entry to KEYS_AND_PLACEHOLDERS in src/friendly/keys.rs (the keys_validate_against_catalog test enforces both). 4a keys:

• ddl.sql_create_table — the per-command help_id body.
• parse.usage.sql_create_table — the usage skeleton.
• diagnostic.* DDL peers of the ADR-0033 DML diagnostics: unknown type, duplicate column name (and any 4a-relevant pre-submit checks).
• The IF NOT EXISTS skipped note key.

All wording engine-neutral (no SQLite/STRICT/PRAGMA) — the vocab audit enforces it.

5. Out of 4a scope (no pre-emptive cuts — just later sub-phases)

• Foreign keys: inline REFERENCES + table-level FOREIGN KEY → 4b.
• DROP TABLE [IF EXISTS] → 4c. (IF EXISTS no-op-with-note reuses the 4.4 mechanism.)
• Indexes, ALTER TABLE, ALTER COLUMN TYPE, table rename → 4d–4h.
• Composite UNIQUE(a,b) / multi-column table CHECK → 4a.2 (a persistence-model extension; see §6). 4a accepts single-column table-level UNIQUE(a) / CHECK(expr-over-one-col) by normalizing them into the column spec (free — ColumnSchema already carries per-column unique/check), and rejects the composite/multi-column forms with a "not yet supported" message until 4a.2 lands.
• CREATE TABLE … AS SELECT (CTAS): not in ADR-0035's surface at all — an ordinary parse error, not a deferral.

6. Decisions settled this round (user-confirmed) + the 4a/4a.2 split

1. 4a/4a.2 split (user-confirmed). Composite UNIQUE(a,b) and multi-column table CHECK are deferred to a dedicated slice 4a.2. Rationale (the general rule): a DDL feature needs data-model work exactly when it introduces a structure simple mode could never produce — not merely new syntax. Almost all of advanced DDL (per-column constraints, compound PK, FK, indexes, drop, alter-column) maps onto structures the model already persists (ColumnSchema, TableSchema.primary_key, RelationshipSchema, IndexSchema), so it is syntax-only + reuse. Composite UNIQUE / table CHECK are the first structures with no slot in TableSchema, so they need a model + round-trip extension and earn their own slice. Same class, already on the radar: CREATE UNIQUE INDEX (4d — IndexSchema has no unique field; ADR-0025 deferred it) and table rename (4h — a new low-level op the ADR already flags).

   4a.2 scope (its own test-first slice, after 4a core):

   • Extend TableSchema (src/persistence/mod.rs) with table-level constraint slots — e.g. unique_constraints: Vec<Vec<String>> and check_constraints: Vec<String>.
   • Extend the YAML writer/parser + RawTable (src/persistence/yaml.rs) — additive, backward-compatible, optional-on-read (the pattern used when unique/not_null/ check were added; no migration needed).
   • Extend read_schema_snapshot (src/db.rs ~2225) to detect composite UNIQUE / table CHECK from the database.
   • Extend do_create_table to emit them in the DDL.
   • Extend the SqlCreateTable command shape + grammar to carry/parse them (lifting the 4a "not yet supported" rejection).
   • Round-trip tests (save → load → rebuild) proving they survive, on top of parse/execute/undo coverage.

2. No-op-with-note plumbing — mechanism (a) (the CreateOutcome enum, §4.4). Explicit and reused by DROP TABLE IF EXISTS (4c); chosen now so the worker reply type is designed once.

7. Devil's Advocate review of this plan

• Does it reuse rather than fork execution? Yes — do_create_table is the single executor; SqlCreateTable only differs at the parse/AST layer and the if_not_exists branch. No drift risk. ✓
• Is the dispatch genuinely the proven precedent? Yes — same category-grouped SQL-first/simple-fallback as insert. The plan verifies the simple-mode form still parses in advanced mode (a real fallback test, not just the SQL happy path). ✓
• Undo actually one step? The plan wires snapshot_then exactly as the existing arms and adds a dedicated undo test (create = one step, undo drops + clears metadata, redo recreates). ✓
• Silent scope drop? The table-level UNIQUE/CHECK gap was the one place 4a could quietly under-deliver against §4's surface — it was escalated and resolved as the 4a.2 split (§6), with composite forms rejected by an explicit "not yet supported" message (not a confusing parse error), not silently dropped. ✓
• Engine neutrality? All new strings are catalog keys subject to the vocab audit; the plan names no engine in user-facing text. ✓
• Tests first? §8 orders failing tests before code at every step. ✓

8. Implementation sequence (test-first throughout)

1. Type-alias resolver — write Tier-1 tests for the §2.5 map (canonical + aliases + length-ignored + unknown→None) → red → add resolve_type_name → green.
2. Command + parser — write Tier-1 ast_builder tests (valid columns/types/constraints, compound PK, single-column table-level UNIQUE/CHECK normalized, INTEGER PRIMARY KEY→int, IF NOT EXISTS flag; FK-shape and composite UNIQUE(a,b) / multi-column CHECK rejected "not yet supported") → red → add Command::SqlCreateTable, sql_create_table.rs, REGISTRY entry → green. Include a fallback test: simple create … with pk still parses in advanced mode.
3. Worker — write Tier-3 tests/sql_create_table.rs (metadata, CSV, describe; alias end-to-end; IF NOT EXISTS no-op-with-note; duplicate-table plain error) → red → add Request::SqlCreateTable + snapshot_then arm + the §4.4 outcome + reuse do_create_table → green.
4. Undo — write the undo Tier-3 test (one step; undo/redo) → red → confirm it passes (the snapshot_then wrap should make it green with no extra code; if not, the wrap is wrong) → green.
5. Friendly catalog/keys — add the 4a keys + bodies; run keys_validate_against_catalog and the vocab audit → green.
6. Full sweep — cargo test (expect 1698 + new, 0 fail, 0 skip) and cargo clippy --all-targets -- -D warnings clean. Compare against the §1 baseline; no regressions.
7. Docs — flip ADR-0035 to Accepted (README in lockstep); update requirements.md Q4. Propose the commit message; wait for approval.

9. Engine-neutral string notes (ADR-0002)

Every user-facing string added in 4a — help body, usage skeleton, diagnostics, the IF NOT EXISTS skipped note, the unknown-type and duplicate-column messages — refers to "the table" / "the database" / "the type", never SQLite / STRICT / PRAGMA / rusqlite. The vocab audit test is the gate.

10. Exit gate for 4a (mirrors ADR-0035 §13 / ADR-0033)

• All §3 checklist items satisfied or explicitly escalated (§6).
• All four tiers green, zero skips; baseline not regressed.
• A written DA pass on the delivered slice (not just this plan).
• ADR-0035 flipped Proposed → Accepted; requirements.md updated.

11. Next action after approval

All design questions are settled (§2, §6). Start at §8 step 1: the type-alias resolver, test-first. 4a.2 (composite UNIQUE / table CHECK, §6.1) follows 4a as its own test-first slice.