REPL help ships an unparseable PARTITIONED BY clause (help JSON is part of the artefact)

[fupelaqu]

Summary

The REPL help for CREATE TABLE documents the partitioning clause as PARTITIONED BY. That spelling has never parsed. Unlike the prose documentation, this ships inside the artefact — core/src/main/resources/help/** is packaged into the REPL and the -all bundles — so a user who types \h CREATE TABLE is handed a form that cannot work, offline, from the product itself.

The prose docs were corrected in SoftClient4ES#243 and softclient4es-web#40. This issue covers the help JSON only.

The real syntax

// sql/.../parser/Parser.scala:355
opt(keyword("PARTITION") ~ keyword("BY") ~ ident ~ opt(granularity))

Verified against the parser:

form	result
) PARTITIONED BY (timestamp MONTH) ← as the help says	FAIL end of input expected
) PARTITION BY timestamp (MONTH)	OK
) PARTITION BY timestamp MONTH	FAIL — parentheses required
) PARTITION BY timestamp	OK — granularity defaults to DAY

Where

core/src/main/resources/help/commands/ddl/create_table.json

line	content	wrong in
14	"[PARTITIONED BY column (granularity)]"	keyword only — arg shape is right
72	"name": "PARTITIONED BY"	keyword
126	example: ) PARTITIONED BY (timestamp MONTH)	keyword and arg shape
131	example: ) PARTITIONED BY (created_at MONTH)	keyword and arg shape

core/src/main/resources/help/commands/ddl/alter_table.json:205 — "Cannot change PARTITIONED BY after creation" — prose, keyword only.

Note the file is internally inconsistent: line 14 gives the correct argument shape (column (granularity)) while the two worked examples give the wrong one. Whichever a user copies, the keyword is wrong.

Why this is worth more than a spelling fix

Before #214 made trailing input a hard error, the parser silently dropped the unrecognised clause. Copying the help example produced a plain concrete index instead of an index template, with no error — a wrong result rather than a failure. Since #214 it fails loudly, which is how it surfaced.

Suggested fix

1. PARTITIONED BY → PARTITION BY in all five places.
2. Correct the two examples to ) PARTITION BY <column> (<granularity>).
3. Consider a test asserting that every "sql" value in the help JSON parses. This is the same class as the phantom help entries for unimplemented functions; a mechanical gate would catch the whole family rather than this instance.

How it was found

Parse-probing the documentation SQL examples through Parser.apply; the help JSON surfaced while tracing where else the wrong form appears.