docs: align managed runtime examples

examples/package-artifacts/README.md

@@ -4,14 +4,18 @@ The package artifact smoke checks create temporary projects instead of storing
 sample projects in this directory. Run the checks from `ktx/`:
 
 ```bash
-source .venv/bin/activate
 pnpm run artifacts:check
 ```
 
-The npm smoke project installs the generated `@ktx/context` and `@ktx/cli`
-tarballs, imports public package entry points, and runs installed `ktx`
-commands against a generated local project.
+The npm smoke project installs the generated public `@kaelio/ktx` tarball,
+imports the package entry point, and runs installed `ktx` commands against a
+generated local project.
 
-The Python smoke project installs `ktx-daemon` through the local artifact
-directory, imports `semantic_layer` and `ktx_daemon`, and runs
-`python -m ktx_daemon semantic-validate`.
+The managed Python runtime smoke isolates `KTX_RUNTIME_ROOT`, verifies
+`ktx runtime status`, runs `ktx sl query --yes` to install the core runtime from
+the bundled wheel, checks `ktx runtime doctor`, starts and reuses the managed
+daemon, and stops it.
+
+The Python smoke project still installs the Python artifacts directly because
+it verifies the standalone Python distributions that feed the bundled runtime
+wheel.

examples/postgres-historic/README.md

@@ -13,8 +13,8 @@ generates query workload under separate users, runs `ktx setup` with
 
 - Docker with Compose v2
 - Node and pnpm matching the KTX workspace
-- `python-service/.venv` already created, or `KTX_SQL_ANALYSIS_URL` pointing at
-  a running service that exposes `/api/sql/analyze-for-fingerprint`
+- `uv` on `PATH` so the KTX-managed Python runtime can install the bundled
+  runtime wheel
 
 ## Run
 
@@ -24,8 +24,9 @@ From the KTX repository root:
 examples/postgres-historic/scripts/smoke.sh
 ```
 
-The smoke creates a temporary KTX project, starts Postgres on
-`127.0.0.1:55432`, and uses this connection URL:
+The smoke creates a temporary KTX project, isolates the managed Python runtime
+under the temporary project parent, starts Postgres on `127.0.0.1:55432`, and
+uses this connection URL:
 
 ```bash
 postgresql://ktx_reader:ktx_reader@127.0.0.1:55432/analytics # pragma: allowlist secret
@@ -83,10 +84,11 @@ Historic SQL (warehouse)` when `pg_stat_statements` is installed,
 Run local historic-SQL ingest:
 
 ```bash
-node packages/cli/dist/bin.js --project-dir /tmp/ktx-postgres-historic dev ingest run \
+pnpm run ktx -- dev ingest run --project-dir /tmp/ktx-postgres-historic \
   --connection-id warehouse \
   --adapter historic-sql \
   --plain \
+  --yes \
   --no-input
 ```
 
@@ -111,5 +113,6 @@ The manifest should have `dialect: "postgres"`, `degraded: true`,
 - Missing grants: confirm `GRANT pg_read_all_stats TO ktx_reader;`.
 - Empty templates: rerun `scripts/generate-workload.sh base` and keep
   `--historic-sql-min-calls 2` for the smoke.
-- SQL-analysis failures: set `KTX_SQL_ANALYSIS_URL` to the running service URL
-  or create `python-service/.venv` before running `scripts/smoke.sh`.
+- SQL-analysis failures: run `pnpm run ktx -- runtime doctor` from the KTX
+  repository root and confirm `uv`, the bundled Python wheel, and the managed
+  runtime all pass.

examples/postgres-historic/scripts/smoke.sh

@@ -4,17 +4,17 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 EXAMPLE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 KTX_ROOT="$(cd "$EXAMPLE_DIR/../.." && pwd)"
-REPO_ROOT="$(cd "$KTX_ROOT/.." && pwd)"
 COMPOSE_FILE="$EXAMPLE_DIR/docker-compose.yml"
 PROJECT_PARENT="${KTX_POSTGRES_HISTORIC_PROJECT_PARENT:-$(mktemp -d)}"
 PROJECT_DIR="$PROJECT_PARENT/postgres-historic-ktx"
 KTX_BIN="$KTX_ROOT/packages/cli/dist/bin.js"
-PYTHON_SERVICE_LOG="$PROJECT_PARENT/python-service.log"
-PYTHON_SERVICE_PID=""
+export KTX_RUNTIME_ROOT="$PROJECT_PARENT/managed-runtime"
+unset KTX_DAEMON_URL
+unset KTX_SQL_ANALYSIS_URL
 
 cleanup() {
-  if [[ -n "$PYTHON_SERVICE_PID" ]]; then
-    kill "$PYTHON_SERVICE_PID" >/dev/null 2>&1 || true
+  if [[ -f "$KTX_BIN" ]]; then
+    node "$KTX_BIN" runtime stop >/dev/null 2>&1 || true
   fi
   if [[ "${KTX_POSTGRES_HISTORIC_KEEP_DOCKER:-0}" != "1" ]]; then
     docker compose -f "$COMPOSE_FILE" down -v >/dev/null 2>&1 || true
@@ -22,31 +22,6 @@ cleanup() {
 }
 trap cleanup EXIT
 
-start_sql_analysis_if_needed() {
-  if [[ -n "${KTX_SQL_ANALYSIS_URL:-}" ]]; then
-    return
-  fi
-  if [[ ! -d "$REPO_ROOT/python-service/.venv" ]]; then
-    echo "Set KTX_SQL_ANALYSIS_URL or create python-service/.venv before running this smoke." >&2
-    exit 1
-  fi
-  (
-    cd "$REPO_ROOT/python-service"
-    source .venv/bin/activate
-    uvicorn app.main:app --host 127.0.0.1 --port 18081 >"$PYTHON_SERVICE_LOG" 2>&1
-  ) &
-  PYTHON_SERVICE_PID="$!"
-  export KTX_SQL_ANALYSIS_URL="http://127.0.0.1:18081"
-  for _ in $(seq 1 60); do
-    if curl -fsS "$KTX_SQL_ANALYSIS_URL/health" >/dev/null 2>&1; then
-      return
-    fi
-    sleep 1
-  done
-  echo "SQL analysis service did not become healthy. Log: $PYTHON_SERVICE_LOG" >&2
-  exit 1
-}
-
 latest_manifest() {
   find "$PROJECT_DIR/raw-sources/warehouse/historic-sql" -name manifest.json | sort | tail -n 1
 }
@@ -83,9 +58,19 @@ const jobId = process.argv[4];
 const { loadKtxProject } = await import(join(ktxRoot, 'packages/context/dist/project/index.js'));
 const { runLocalStageOnlyIngest } = await import(join(ktxRoot, 'packages/context/dist/ingest/index.js'));
 const { createKtxCliLocalIngestAdapters } = await import(join(ktxRoot, 'packages/cli/dist/local-adapters.js'));
+const { getKtxCliPackageInfo } = await import(join(ktxRoot, 'packages/cli/dist/index.js'));
 
 const project = await loadKtxProject({ projectDir });
-const adapters = createKtxCliLocalIngestAdapters(project, { historicSqlConnectionId: 'warehouse' });
+const cliVersion = getKtxCliPackageInfo().version;
+const managedRuntimeIo = { stdout: process.stdout, stderr: process.stderr };
+const adapters = createKtxCliLocalIngestAdapters(project, {
+  historicSqlConnectionId: 'warehouse',
+  managedDaemon: {
+    cliVersion,
+    installPolicy: 'auto',
+    io: managedRuntimeIo,
+  },
+});
 const adapter = adapters.find((candidate) => candidate.source === 'historic-sql');
 if (!adapter) throw new Error('historic-sql adapter was not registered for local run');
 const record = await runLocalStageOnlyIngest({
@@ -111,7 +96,6 @@ NODE
 cd "$KTX_ROOT"
 pnpm --filter @ktx/context run build
 pnpm --filter @ktx/cli run build
-start_sql_analysis_if_needed
 
 docker compose -f "$COMPOSE_FILE" up -d --wait
 "$EXAMPLE_DIR/scripts/generate-workload.sh" base