Source contract rejects column/grain names containing "." — blocks sl_query for the source

[andreybavt]

Summary

A resolved semantic-layer source fails the TS/Python contract when a grain entry or a columns[].name contains a .:

resolved source '' violates the TS/Python contract: grain.3: must be unqualified (no '.') — use the output column name; columns.3.name: must be unqualified (no '.') — use the output column name

The guard is packages/cli/src/context/sl/schemas.ts (regex /^[^.]+$/, "must be unqualified"), thrown as ComposeContractError in packages/cli/src/context/sl/semantic-layer.service.ts.

Impact

This is thrown on every query that touches the source, so an affected source is entirely unusable for sl_query — a hard block, not a one-off. Observed persisting across a single install's session in usage telemetry (dozens of occurrences), on a source with non-ASCII (CJK) column identifiers, at least one of which contains a ..

Root cause — needs investigation

Two possibilities to confirm:

1. The warehouse legitimately has a column whose name contains a .; ktx source generation carries it verbatim into columns[].name/grain, and the contract then rejects it → generation/ingest should escape/normalize, or the contract should accept quoted dotted identifiers.
2. Source generation is emitting a qualified table.column name where a bare output-column name is expected → fix the generator.

Either way it's a real defect: ktx generated (or accepted) a source it then refuses to query.

Suggested direction

Decide whether dotted column names are supported (quote/escape and thread through the contract) or normalized at generation time, then ensure ingest/source-generation always produces contract-valid names so a generated source is guaranteed queryable. A regression test with a dotted / non-ASCII column identifier would lock it in.

[sricursion]

I'd like to claim this one.

Plan: first reproduce both suspected paths to pin down whether the warehouse column legitimately contains a . (carried verbatim into columns[].name/grain) or whether source generation emits a qualified table.column where an output-column name belongs. My leaning, unless investigation says otherwise: keep the unqualifiedNameSchema contract in packages/cli/src/context/sl/schemas.ts strict, and fix generation/ingest so every emitted source is contract-valid — normalize dotted identifiers to a safe output-column alias at generation time and thread the quoted physical reference through the SQL expr, so a generated source is guaranteed queryable. Regression tests with a dotted and a non-ASCII (CJK) column identifier to lock it in. I'll confirm the root cause on this issue before opening the PR in case it changes the direction.

[anentropic]

I'm doing my first ktx setup and just hit this too

I have Snowflake warehouse

Claude says:

Root cause

ktx's semantic-layer contract forbids a . in any column or grain name — it treats . as a table qualifier:

// dist/context/sl/schemas.js
const unqualifiedNameSchema = z.string().min(1)
  .regex(/^[^.]+$/, "must be unqualified (no '.') — use the output column name");

But the Snowflake table TRIAGE_MEDIA_DETAIL (and its near-duplicate siblings _PART1 / _PART2) has 77 physical columns whose names literally contain a period — e.g. No.of RO Sent with Walk-around Video, No.of Authorisations Opened. I confirmed these are the real physical column names from the raw scan, not a mistake in the overlay.

ktx genuinely cannot represent these columns:

• Keep the name → schema rejects the .
• Rename without expr → validator flags it "absent from physical table"
• Alias via expr: '"No.of ..."' → the expr identifier-scanner strips quotes and splits on spaces/dots, so No.of RO Sent... becomes tokens of, RO, Sent… and fails the reference check

And because one broken resolved source fails the whole manifest, ktx sl is globally blocked right now — even ktx sl read CONNECT_LOGIN_COUNTS (unaffected table) returns this error. So fixing it unblocks the entire semantic layer.