fix(context): merge overlay columns onto manifest columns by name (#94)

* fix(context): merge overlay columns onto manifest columns by name

composeOverlay was appending overlay columns to the manifest column list,
producing duplicate entries when dbt/metabase overlays declared a column
just to attach descriptions. The duplicates carried no `type`, so the
pydantic SourceDefinition rejected them at semantic-query time and broke
`ktx sl query` for every overlay-backed measure. Now overlay columns
match base columns by name (case-insensitive): same-name entries merge
onto the manifest (overlay fields win, type/role fall back to the base,
descriptions merge per source key) and only new names append.

* refactor(sl): split overlay columns from column_overrides and enforce TS/Python wire contract

Overlay sources now have two distinct collections: `columns:` for computed
columns (requiring `expr` + `type`) and `column_overrides:` for metadata
patches to inherited manifest columns. Composing or loading an overlay that
mixes the two — or references an unknown column — fails with a typed error.

Introduce `ResolvedSemanticLayerSource` / `resolvedSourceSchema` /
`toResolvedWire` as the strict shape sent to the Python engine, and add a
schema contract test that diffs Zod against the Pydantic JSON schema dumped
by `python -m semantic_layer dump-schema`. `SourceDefinition` is now
`extra="forbid"` on the Python side.

`loadAllSources` surfaces per-file load errors instead of swallowing them,
so validation/query paths can report manifest shard parse failures.

* fix(context): make scan description generation resilient and quiet

A transient sampleTable failure during ingest used to take out every
table in a connection: generateTableDescription returned a hardcoded
'Table not found' string into descriptions.ai, and KtxDescriptionGenerator
was constructed without a logger, so the failure left no trail anywhere.

- sampleTable / sampleColumn calls retry 3x with 200/400/800ms backoff,
  honouring KtxScanContext.signal via a new KtxAbortedError.
- On retry exhaustion or missing capability, table generation falls back
  to a metadata-only prompt built from column name / native type / comment
  / rawDescriptions. The column path follows the same rule -- call the
  LLM when any of samples or rawDescriptions are available; skip only
  when both are absent.
- Logger is now threaded from KtxScanContext into the generator. Failures
  emit structured KtxScanWarning entries (new description_fallback_used
  code, plus existing sampling_failed / enrichment_failed /
  connector_capability_missing). ktx scan groups warnings by code so a
  batch of identical failures collapses to one summary line plus sample.
- Returns null on failure instead of the 'Table not found' sentinel; the
  manifest writer's existing guard already skips empty descriptions, so
  schema YAML no longer carries misleading text. SCAN_MANAGED_DESCRIPTION_KEYS
  already strips stale 'ai' on merge, so existing YAML clears on next run.

Also suppress AI SDK v6 'system in messages' warning: pull system messages
out of KtxMessageBuilder.wrapSimple's output via a new splitKtxSystemMessages
helper and pass them top-level to generateText (preserves cacheControl
providerOptions on the SystemModelMessage). Agent-runner's local
splitSystemPromptMessages dedupes onto the shared helper.

* test(docs): align examples-docs assertions with revamped docs

PR #103 (setup/guide doc revamp) reworded several CLI examples and
connection labels; the assertions in scripts/examples-docs.test.mjs
still referenced the pre-revamp wording and were failing in CI on main.
Update the regexes to match the post-revamp content:

- drop the `--json` flag from the sl-query example expectation
- move the `Driver:` / `Status: ok` probe to the connection reference,
  which is where that output now lives (driver id is lowercase
  `postgres`, not the display name `PostgreSQL`)
- drop the obsolete `Install \`uv\`...` troubleshooting line
- accept `<connectionId>` everywhere; the docs no longer use the
  hyphenated `<connection-id>` form
- match the `warehouse` connection id used in the quickstart instead of
  the `postgres-warehouse` id only used in the README and setup ref

* fix(sl): skip TS/Python schema contract test when uv is unavailable

The TypeScript checks CI job does not install uv or Python, so the
module-level `execFileSync('uv', ...)` in schemas.contract.test.ts threw
ENOENT and failed the suite. Wrap the schema dump in a try/catch and
guard the describe block with `describe.skipIf` so the test skips in
environments without uv. Local dev and any CI job that has uv on PATH
still runs the cross-language contract assertion.

scripts/examples-docs.test.mjs

@@ -168,7 +168,7 @@ describe('standalone example docs', () => {
       'ktx status --json',
       'ktx sl list --json',
       'ktx sl search "revenue" --json',
-      'ktx sl query --json',
+      'ktx sl query',
       'ktx wiki search "revenue recognition" --json',
     ]) {
       assert.match(servingAgents, new RegExp(command.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
@@ -183,7 +183,8 @@ describe('standalone example docs', () => {
     assert.match(connectionReference, /ktx connection test my-warehouse/);
     assert.match(connectionReference, /ktx connection test --all/);
     assert.match(quickstart, /Connection test passed/);
-    assert.match(quickstart, /Driver: PostgreSQL .* Status: ok/);
+    assert.match(connectionReference, /Driver: postgres/);
+    assert.match(connectionReference, /Status: ok/);
   });
 
   it('documents public npm and managed runtime usage', async () => {
@@ -195,7 +196,6 @@ describe('standalone example docs', () => {
     assert.match(quickstart, publicPackagePattern('npm install -g {package}'));
     assert.match(quickstart, /ktx dev runtime install --feature local-embeddings --yes/);
     assert.match(quickstart, /ktx dev runtime start --feature local-embeddings/);
-    assert.match(quickstart, /Install `uv`, run `ktx dev runtime status`/);
     assert.match(packageArtifacts, /requires `uv` on `PATH`/);
     assert.match(packageArtifacts, /ktx dev runtime status/);
     assert.match(packageArtifacts, /ktx dev runtime status/);
@@ -255,15 +255,15 @@ describe('standalone example docs', () => {
     assert.match(ingestReference, /ktx ingest <connectionId>/);
     assert.match(ingestReference, /ktx ingest --all --deep/);
     assert.match(ingestReference, /--query-history-window-days <days>/);
-    assert.match(buildingContext, /ktx ingest <connection-id>/);
+    assert.match(buildingContext, /ktx ingest <connectionId>/);
     assert.match(buildingContext, /ktx ingest --all/);
     assert.match(contextSources, /ktx ingest <connectionId>/);
     assert.match(contextAsCode, /ktx ingest --all --no-input/);
     assert.match(quickstart, /schema context/);
     assert.match(primarySources, /context:\n      queryHistory:/);
     assert.match(rootReadme, /Databases configured: yes \(postgres-warehouse\)/);
-    assert.match(quickstart, /Databases:\n  postgres-warehouse: deep context complete/);
-    assert.match(quickstart, /Databases configured: yes \(postgres-warehouse\)/);
+    assert.match(quickstart, /Databases:\n  warehouse: deep context complete/);
+    assert.match(quickstart, /Databases configured: yes \(warehouse\)/);
     assert.match(setupReference, /Databases configured: yes \(postgres-warehouse\)/);
     assert.doesNotMatch(rootReadme, new RegExp(['Primary sources', 'configured'].join(' ')));
     assert.doesNotMatch(quickstart, new RegExp(['Primary', 'sources'].join(' ')));