@@ -15,7 +15,7 @@
     "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {}
   },
   "postCreateCommand": "pip install -e '.[dev]'",
-  "postStartCommand": "bash -lc \"pip install -e ./sdk && cd sdk-ts && npm install && cd .. && if [ ! -f agentflow_demo.duckdb ]; then python -m src.processing.local_pipeline --burst 500; fi\"",
+  "postStartCommand": "bash -lc \"pip install -e ./sdk && cd sdk-ts && npm install && cd .. && if [ ! -f agentflow_demo.duckdb ]; then python -m agentflow_runtime.processing.local_pipeline --burst 500; fi\"",
   "forwardPorts": [8000, 8080, 8081, 8474, 9090, 3000, 9001, 16686],
   "portsAttributes": {
     "8000": {
 
@@ -38,7 +38,7 @@ body:
       label: Affected surface
       multiple: true
       options:
-        - API (`src/serving/api/`)
+        - API (`src/agentflow_runtime/serving/api/`)
         - Python SDK (`sdk/agentflow/`)
         - TypeScript SDK (`sdk-ts/`)
         - Helm chart (`helm/agentflow/`)
 
@@ -75,7 +75,7 @@ updates:
   # apache-flink majors/minors stay individual PRs by default (no group),
   # matching the deliberate-bump policy for the Flink line.
   - package-ecosystem: pip
-    directory: "/src/processing/flink_jobs"
+    directory: "/src/agentflow_runtime/processing/flink_jobs"
     schedule:
       interval: weekly
       day: monday
@@ -149,7 +149,7 @@ updates:
   - package-ecosystem: docker
     directories:
       - "/"
-      - "/src/processing/flink_jobs"
+      - "/src/agentflow_runtime/processing/flink_jobs"
       - "/docker/kafka-connect"
       - "/.devcontainer"
     schedule:
 
@@ -32,7 +32,7 @@ jobs:
 
           import duckdb
 
-          from src.serving.backends.duckdb_backend import DuckDBBackend
+          from agentflow_runtime.serving.backends.duckdb_backend import DuckDBBackend
 
           pipeline_db = Path("agentflow_demo.duckdb")
           usage_db = Path("agentflow_api.duckdb")
 
@@ -87,19 +87,44 @@ jobs:
         run: |
           uv run python -m build --wheel --no-isolation
           uv run python -m build --wheel --no-isolation --outdir dist sdk
+      - name: Wheel top-level namespace policy (audit F-09)
+        # The runtime wheel must ship exactly agentflow_runtime + the one-file
+        # deprecated src shim; any other top-level entry is an undeclared
+        # package leaking into the distribution.
+        run: uv run python scripts/wheel_smoke.py 'dist/agentflow_runtime-*.whl'
       - name: Install production dependencies and wheel in a clean environment
         run: |
           python -m venv /tmp/agentflow-clean
           /tmp/agentflow-clean/bin/pip install --quiet --require-hashes -r requirements-docker.lock
           /tmp/agentflow-clean/bin/pip install --quiet --no-deps dist/agentflow_runtime-*.whl
           /tmp/agentflow-clean/bin/pip install --quiet --no-deps dist/agentflow_client-*.whl
           /tmp/agentflow-clean/bin/pip check
-      - name: Smoke quickstart and materializer imports
-        # Run outside the checkout so `src.*` must come from the installed
-        # runtime wheel rather than the repository working tree on sys.path.
+      - name: Smoke quickstart, materializer and deprecated-shim imports
+        # Run outside the checkout so the runtime must come from the installed
+        # wheel rather than the repository working tree on sys.path. The src.*
+        # surface must keep working through the wheel's deprecated shim for
+        # one deprecation window (removed in the next major release).
         working-directory: /tmp
         run: |
-          /tmp/agentflow-clean/bin/python -c "from agentflow.client import AgentFlowClient; from src.serving.api.main import app; from src.processing.local_pipeline import main; from src.processing.lake_consumer import ValidatedLakeConsumer; assert AgentFlowClient and app and main and ValidatedLakeConsumer"
+          /tmp/agentflow-clean/bin/python - <<'PY'
+          import warnings
+
+          from agentflow.client import AgentFlowClient
+          from agentflow_runtime.processing.lake_consumer import ValidatedLakeConsumer
+          from agentflow_runtime.processing.local_pipeline import main
+          from agentflow_runtime.serving.api.main import app
+
+          assert AgentFlowClient and app and main and ValidatedLakeConsumer
+
+          with warnings.catch_warnings(record=True) as caught:
+              warnings.simplefilter("always")
+              import src.serving.api.main as shim_main
+
+          assert any(
+              issubclass(w.category, DeprecationWarning) for w in caught
+          ), "src shim import did not raise DeprecationWarning"
+          assert shim_main.app is app, "src shim aliased a different module object"
+          PY
 
   local-duckdb-smoke:
     runs-on: ubuntu-latest
@@ -231,25 +256,25 @@ jobs:
           # --cov-branch turns the floor into a combined line+branch metric — local baseline
           # 2026-05-25 is 62% (7716 lines / 2010 branches measured on HEAD `22b1be9`), so the
           # 60% gate stays passing with a 2pp cushion. Raise the gate once that cushion grows.
-          python -m pytest tests/unit/ tests/property/ -v --tb=short --cov=src --cov=sdk --cov-branch --cov-report=xml --cov-report=term-missing --cov-fail-under=60
+          python -m pytest tests/unit/ tests/property/ -v --tb=short --cov=src/agentflow_runtime --cov=sdk --cov-branch --cov-report=xml --cov-report=term-missing --cov-fail-under=60
       - name: Enforce changed-code coverage
         run: diff-cover coverage.xml --compare-branch=origin/main --fail-under=80
       - name: Run quality validators coverage gate
         run: |
-          python -m pytest tests/unit/test_validators.py -v --tb=short --cov=src.quality.validators --cov-report=term-missing --cov-fail-under=90
+          python -m pytest tests/unit/test_validators.py -v --tb=short --cov=agentflow_runtime.quality.validators --cov-report=term-missing --cov-fail-under=90
       - name: Run freshness monitor coverage gate
         run: |
-          python -m pytest tests/unit/test_freshness_monitor.py -v --tb=short --cov=src.quality.monitors.freshness_monitor --cov-report=term-missing --cov-fail-under=90
+          python -m pytest tests/unit/test_freshness_monitor.py -v --tb=short --cov=agentflow_runtime.quality.monitors.freshness_monitor --cov-report=term-missing --cov-fail-under=90
       - name: Run event producer coverage gate
         run: |
-          python -m pytest tests/unit/test_event_producer.py -v --tb=short --cov=src.ingestion.producers.event_producer --cov-report=term-missing --cov-fail-under=90
+          python -m pytest tests/unit/test_event_producer.py -v --tb=short --cov=agentflow_runtime.ingestion.producers.event_producer --cov-report=term-missing --cov-fail-under=90
       - name: Run SQL guard coverage gate
         run: |
           # Security-critical NL->SQL guard: validate_nl_sql (SELECT-only, no DML,
           # tenant table allow-list, recursive-CTE shadow reject). test_sql_guard
           # plus test_sql_guard_mutation give full module coverage (100% local);
           # the 90% gate keeps a 10pp regression cushion.
-          python -m pytest tests/unit/test_sql_guard.py tests/unit/test_sql_guard_mutation.py -v --tb=short --cov=src.serving.semantic_layer.sql_guard --cov-report=term-missing --cov-fail-under=90
+          python -m pytest tests/unit/test_sql_guard.py tests/unit/test_sql_guard_mutation.py -v --tb=short --cov=agentflow_runtime.serving.semantic_layer.sql_guard --cov-report=term-missing --cov-fail-under=90
       - name: Run rate limiter coverage gate
         run: |
           # Security-critical sliding-window rate limiter (Redis + in-memory
 
@@ -52,7 +52,7 @@ jobs:
           set -euo pipefail
           mkdir -p .artifacts/load
           python tests/load/run_load_test.py --duckdb-path "$DUCKDB_PATH" --seed-data --seed-only
-          python -m uvicorn src.serving.api.main:app --host 127.0.0.1 --port 8011 > .artifacts/load/api.log 2>&1 &
+          python -m uvicorn agentflow_runtime.serving.api.main:app --host 127.0.0.1 --port 8011 > .artifacts/load/api.log 2>&1 &
           api_pid=$!
           trap 'kill "$api_pid"' EXIT
           python scripts/wait_for_services.py --url http://127.0.0.1:8011 --timeout 120
 
@@ -42,7 +42,7 @@ jobs:
           mkdir -p .artifacts/perf-smoke docs/perf
           docker compose up -d --wait redis
           python tests/load/run_load_test.py --duckdb-path "$DUCKDB_PATH" --seed-data --seed-only
-          python -m uvicorn src.serving.api.main:app --host 127.0.0.1 --port 8012 > .artifacts/perf-smoke/api.log 2>&1 &
+          python -m uvicorn agentflow_runtime.serving.api.main:app --host 127.0.0.1 --port 8012 > .artifacts/perf-smoke/api.log 2>&1 &
           api_pid=$!
           trap 'kill "$api_pid" 2>/dev/null || true; docker compose stop redis >/dev/null 2>&1 || true' EXIT
           python scripts/wait_for_services.py --url http://127.0.0.1:8012 --timeout 120
 
@@ -176,7 +176,7 @@ jobs:
                           f"- Extra `[{extra_name}]` (root `pyproject.toml`): resolved install ({extra_count} packages)\n"
                       )
                   handle.write(
-                      f"- Flink runtime (`src/processing/flink_jobs/requirements.txt`): resolved install ({flink_count} packages)\n"
+                      f"- Flink runtime (`src/agentflow_runtime/processing/flink_jobs/requirements.txt`): resolved install ({flink_count} packages)\n"
                   )
                   handle.write("- Exclusions: dev/CI/test extras, local tooling, and unrelated Docker image packages\n")
           PY
@@ -219,7 +219,7 @@ jobs:
           # newest PyPI release (checked 2026-07-20) and itself caps
           # pyarrow<21; beam accepts pyarrow<24 only from 2.75.0, which no
           # released apache-flink allows. Dependabot watches the Flink
-          # manifest (src/processing/flink_jobs), so the next apache-flink
+          # manifest (src/agentflow_runtime/processing/flink_jobs), so the next apache-flink
           # release opens a PR — re-check this ignore there. Remove when the
           # resolved flink-runtime bucket installs pyarrow>=23.0.1.
           # Do NOT retry "uninstall unused pyarrow from the image" — probed
 
@@ -11,6 +11,7 @@ COPY LICENSE /build/LICENSE
 COPY CHANGELOG.md /build/CHANGELOG.md
 COPY requirements.txt /build/requirements.txt
 COPY src /build/src
+COPY packaging /build/packaging
 
 RUN pip install --no-cache-dir --upgrade pip build hatchling \
     && python -m build --wheel --outdir /tmp/dist
@@ -89,4 +90,4 @@ EXPOSE 8000
 # image was the one place still asking the question that cannot get a no.
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health/ready', timeout=3).read()" || exit 1
 
-CMD ["uvicorn", "src.serving.api.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uvicorn", "agentflow_runtime.serving.api.main:app", "--host", "0.0.0.0", "--port", "8000"]
@@ -33,11 +33,11 @@ wait-healthy:
 	@echo "Service UIs: http://localhost:8081 (Flink), http://localhost:9001 (MinIO console)"
 
 produce:
-	python -m src.ingestion.producers.event_producer
+	python -m agentflow_runtime.ingestion.producers.event_producer
 
 api:
 	docker compose up -d redis
-	DUCKDB_PATH=agentflow_demo.duckdb uvicorn src.serving.api.main:app --host 0.0.0.0 --port 8000 --reload
+	DUCKDB_PATH=agentflow_demo.duckdb uvicorn agentflow_runtime.serving.api.main:app --host 0.0.0.0 --port 8000 --reload
 
 tools:
 	python scripts/export_openapi.py
@@ -56,10 +56,10 @@ demo:
 	@echo "Step 0.5: Provisioning the serving store (schema + demo rows)..."
 	@echo "  The API does not create or seed a store on boot any more (audit P0-2)."
 	@echo "  A real deployment runs this same command WITHOUT --seed, from a job."
-	DUCKDB_PATH=agentflow_demo.duckdb python -m src.serving.provision --schema --seed
+	DUCKDB_PATH=agentflow_demo.duckdb python -m agentflow_runtime.serving.provision --schema --seed
 	@echo ""
 	@echo "Step 1: Seeding 500 events through the full pipeline..."
-	python -m src.processing.local_pipeline --burst 500
+	python -m agentflow_runtime.processing.local_pipeline --burst 500
 	@echo ""
 	@echo "Step 1.5: Seeding benchmark fixture rows into agentflow_demo.duckdb..."
 	python -c "from pathlib import Path; from scripts.run_benchmark import seed_benchmark_fixtures; seed_benchmark_fixtures(Path('agentflow_demo.duckdb'))"
@@ -69,10 +69,10 @@ demo:
 	@echo "  Try:  curl http://localhost:8000/v1/metrics/revenue?window=24h"
 	@echo "  Try:  curl http://localhost:8000/v1/entity/user/USR-10001"
 	@echo "  Try:  curl http://localhost:8000/v1/health"
-	AGENTFLOW_AUTH_DISABLED=true DUCKDB_PATH=agentflow_demo.duckdb uvicorn src.serving.api.main:app --host 0.0.0.0 --port 8000
+	AGENTFLOW_AUTH_DISABLED=true DUCKDB_PATH=agentflow_demo.duckdb uvicorn agentflow_runtime.serving.api.main:app --host 0.0.0.0 --port 8000
 
 pipeline:
-	python -m src.processing.local_pipeline --eps 10
+	python -m agentflow_runtime.processing.local_pipeline --eps 10
 
 flink-local:
 ifeq ($(OS),Windows_NT)
@@ -93,7 +93,7 @@ test-integration:
 	pytest tests/integration/ -v --tb=short -m integration
 
 quality:
-	python -m src.quality.validators.semantic_validator --check-all
+	python -m agentflow_runtime.quality.validators.semantic_validator --check-all
 
 # ── Load Testing ──────────────────────────────────────────────────