Add BGSTM external-results smoke workflow pinned to reporter SHA ab5d7c1 with main-branch, audit-log, and artifact-path compatibility hardening

.github/workflows/external-results-smoke.yml

@@ -0,0 +1,146 @@
+name: External Results Smoke
+
+on:
+  pull_request:
+    paths:
+      - 'backend/app/api/external_results.py'
+      - 'backend/app/schemas/external_*.py'
+      - 'backend/app/models/external_*.py'
+      - 'backend/app/crud/external_*.py'
+      - 'backend/alembic/versions/**'
+      - 'docs/specs/external_results_v1.md'
+      - '.github/workflows/external-results-smoke.yml'
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: external-results-smoke-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  smoke:
+    name: External Results contract smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout BGSTM
+        uses: actions/checkout@v4
+        with:
+          path: bgstm
+
+      - name: Checkout bgstm-playwright-frameworks (pinned)
+        uses: actions/checkout@v4
+        with:
+          repository: bg-playground/bgstm-playwright-frameworks
+          ref: ab5d7c1b0740cfbb5004cb6a14851c541364451e
+          path: frameworks
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Set up Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Set up pnpm 9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install smoke script dependencies
+        run: python -m pip install --quiet httpx
+
+      - name: Start BGSTM backend + Postgres
+        run: docker compose -f bgstm/docker-compose.test.yml up -d db backend
+
+      - name: Wait for BGSTM health
+        run: |
+          echo "Waiting for backend health check..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:8001/health > /dev/null; then
+              echo "Backend is healthy"
+              exit 0
+            fi
+            echo "Attempt $i/30 -- backend not ready yet, waiting 5s..."
+            sleep 5
+          done
+          echo "Backend failed to become healthy"
+          docker compose -f bgstm/docker-compose.test.yml logs backend || true
+          exit 1
+
+      - name: Normalize runner token scopes column type for smoke
+        run: |
+          docker compose -f bgstm/docker-compose.test.yml exec -T db psql \
+            -U bgstm_test \
+            -d bgstm_test \
+            -v ON_ERROR_STOP=1 \
+            -c "DO \$\$
+            BEGIN
+              IF EXISTS (
+                SELECT 1
+                FROM information_schema.columns
+                WHERE table_name = 'runner_tokens'
+                  AND column_name = 'scopes'
+                  AND udt_name IN ('json', 'jsonb')
+              ) THEN
+                CREATE OR REPLACE FUNCTION _bgstm_json_to_text_array(j json)
+                RETURNS text[]
+                LANGUAGE sql
+                IMMUTABLE
+                AS \$fn\$
+                  SELECT COALESCE(array_agg(value), ARRAY[]::text[])
+                  FROM json_array_elements_text(j) AS t(value);
+                \$fn\$;
+
+                ALTER TABLE runner_tokens
+                ALTER COLUMN scopes TYPE text[]
+                USING _bgstm_json_to_text_array(scopes);
+
+                DROP FUNCTION _bgstm_json_to_text_array(json);
+              END IF;
+            END
+            \$\$;"
+
+      - name: Verify schema matches migrations
+        run: |
+          docker compose -f bgstm/docker-compose.test.yml exec -T backend alembic current
+          docker compose -f bgstm/docker-compose.test.yml exec -T db psql -U bgstm_test -d bgstm_test -c "\d audit_log"
+
+      - name: Bootstrap project and runner token
+        id: bootstrap
+        run: python bgstm/scripts/smoke/bootstrap.py
+
+      - name: Install frameworks dependencies
+        run: pnpm -C frameworks install --frozen-lockfile
+
+      - name: Build frameworks workspace
+        run: pnpm -C frameworks build
+
+      - name: Install Chromium for crm-example
+        run: pnpm -C frameworks/examples/crm-example exec playwright install --with-deps chromium
+
+      - name: Run crm-example smoke fixture
+        run: |
+          # Playwright fails-by-design (smoke fixture has 1 intentional failure). The real pass/fail signal is the assertion step below.
+          pnpm --filter crm-example -C frameworks smoke || true
+
+      - name: Assert BGSTM persisted expected smoke results
+        id: assert_results
+        run: python bgstm/scripts/smoke/assert.py
+
+      - name: Dump backend logs (always)
+        if: always()
+        run: docker compose -f bgstm/docker-compose.test.yml logs backend
+
+      - name: Tear down BGSTM stack
+        if: always()
+        run: docker compose -f bgstm/docker-compose.test.yml down -v

backend/alembic/versions/j9k0l1m2n3o4_audit_log_details_json.py

@@ -0,0 +1,55 @@
+"""store audit_log.details as JSONB on PostgreSQL
+
+Revision ID: j9k0l1m2n3o4
+Revises: i8j9k0l1m2n3
+Create Date: 2026-05-08 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "j9k0l1m2n3o4"
+down_revision: Union[str, None] = "i8j9k0l1m2n3"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    if bind.dialect.name == "postgresql":
+        op.execute(
+            """
+            ALTER TABLE audit_log
+            ALTER COLUMN details TYPE JSONB
+            USING CASE
+              WHEN details IS NULL OR btrim(details) = '' THEN NULL
+              ELSE details::jsonb
+            END
+            """
+        )
+        return
+
+    op.alter_column("audit_log", "details", existing_type=sa.Text(), type_=sa.JSON(), existing_nullable=True)
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    if bind.dialect.name == "postgresql":
+        op.execute(
+            """
+            ALTER TABLE audit_log
+            ALTER COLUMN details TYPE TEXT
+            USING CASE
+              WHEN details IS NULL THEN NULL
+              ELSE details::text
+            END
+            """
+        )
+        return
+
+    op.alter_column("audit_log", "details", existing_type=sa.JSON(), type_=sa.Text(), existing_nullable=True)

backend/alembic/versions/m2n3o4p5q6r7_merge_external_results_heads.py

@@ -0,0 +1,23 @@
+"""merge external-results migration heads
+
+Revision ID: m2n3o4p5q6r7
+Revises: j9k0l1m2n3o4, l1m2n3o4p5q6
+Create Date: 2026-05-08 17:58:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+# revision identifiers, used by Alembic.
+revision: str = "m2n3o4p5q6r7"
+down_revision: str | Sequence[str] | None = ("j9k0l1m2n3o4", "l1m2n3o4p5q6")
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

backend/app/api/external_results.py

@@ -48,6 +48,7 @@
 
 _WRITE_SCOPE = "external_results:write"
 _READ_SCOPE = "external_results:read"
+_DEFAULT_RUNNER = "@bgstm/playwright-core@unknown"
 
 # ---------------------------------------------------------------------------
 # Artifact upload constants
@@ -141,7 +142,10 @@ async def create_external_session(
     Returns the existing session if an identical session was created within the
     last 60 seconds (idempotency window).
     """
-    session = await create_session(db, payload=payload, runner_token_id=token.id)
+    normalized_payload = payload.model_copy(
+        update={"runner": payload.runner if payload.runner is not None else _DEFAULT_RUNNER}
+    )
+    session = await create_session(db, payload=normalized_payload, runner_token_id=token.id)
     await write_audit(
         db,
         actor_kind="runner_token",
@@ -150,10 +154,10 @@ async def create_external_session(
         resource_type="external_session",
         resource_id=session.id,
         details={
-            "project_id": str(payload.project_id),
-            "git_sha": payload.git_sha,
-            "git_branch": payload.git_branch,
-            "runner": payload.runner,
+            "project_id": str(normalized_payload.project_id),
+            "git_sha": normalized_payload.git_sha,
+            "git_branch": normalized_payload.git_branch,
+            "runner": normalized_payload.runner,
         },
     )
     return _session_to_response(session)

backend/app/schemas/audit_log.py

@@ -1,8 +1,9 @@
+import json
 from datetime import datetime
 from typing import Any
 from uuid import UUID
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, field_validator
 
 
 class AuditLogResponse(BaseModel):
@@ -18,6 +19,28 @@ class AuditLogResponse(BaseModel):
 
     model_config = ConfigDict(from_attributes=True)
 
+    @field_validator("details", mode="before")
+    @classmethod
+    def _normalize_details(cls, value: Any) -> dict[str, Any] | None:
+        if value is None or isinstance(value, dict):
+            return value
+
+        if isinstance(value, str):
+            stripped = value.strip()
+            if not stripped:
+                return None
+            try:
+                parsed = json.loads(stripped)
+            except json.JSONDecodeError:
+                # Preserve invalid historical payloads as structured data instead of
+                # failing audit-log reads for the entire response page.
+                return {"raw": value}
+            if isinstance(parsed, dict):
+                return parsed
+            return {"value": parsed}
+
+        return {"value": value}
+
 
 class AuditLogListResponse(BaseModel):
     entries: list[AuditLogResponse]

backend/app/schemas/external_results.py

@@ -72,7 +72,7 @@ class SessionCreate(BaseModel):
         json_schema_extra={"example": _SESSION_EXAMPLE},
     )
 
-    runner: str = Field(..., description="Identifier of the test runner (name + version).")
+    runner: str | None = Field(None, description="Identifier of the test runner (name + version).")
     project_id: UUID = Field(..., description="BGSTM project this session belongs to.")
     git_sha: str | None = Field(None, description="Full or short commit SHA being tested.")
     git_branch: str | None = Field(None, description="Branch name under test.")

backend/tests/integration/test_external_results_session.py

@@ -151,6 +151,19 @@ def test_create_finish_fetch(self, db_session, write_token):
             assert data3["status"] == "passed"
             assert data3["id"] == session_id
 
+    def test_create_without_runner_defaults_to_bgstm_playwright_core(self, db_session, write_token):
+        _model, plaintext = write_token
+        headers = _auth_header(plaintext)
+        payload = dict(_SESSION_PAYLOAD)
+        payload.pop("runner")
+
+        with TestClient(app) as client:
+            resp = client.post("/api/v1/external-results/session", json=payload, headers=headers)
+
+        assert resp.status_code == 201, resp.text
+        data = resp.json()
+        assert data["runner"].startswith("@bgstm/playwright-core@")
+
 
 # ---------------------------------------------------------------------------
 # Auth: 401 without credentials

backend/tests/test_audit_log.py

@@ -1,6 +1,8 @@
 """Tests for Audit Log functionality"""
 
 import uuid
+from datetime import datetime, timezone
+from types import SimpleNamespace
 
 import pytest
 import pytest_asyncio
@@ -283,3 +285,43 @@ async def override_admin():
         assert data["entries"][0]["resource_type"] == "link"
     finally:
         app.dependency_overrides.pop(get_current_user, None)
+
+
+@pytest.mark.asyncio
+async def test_audit_log_endpoint_parses_string_details(db_session, monkeypatch):
+    """Audit log endpoint normalizes JSON-string details into dictionaries."""
+    admin = _make_admin()
+    db_session.add(admin)
+    await db_session.commit()
+
+    async def fake_get_audit_logs(*_args, **_kwargs):
+        return (
+            [
+                SimpleNamespace(
+                    id=uuid.uuid4(),
+                    actor_kind="runner_token",
+                    user_id=None,
+                    actor_token_id=uuid.uuid4(),
+                    action="external_results.session.start",
+                    resource_type="external_session",
+                    resource_id=str(uuid.uuid4()),
+                    details='{"project_id":"smoke-project"}',
+                    created_at=datetime.now(timezone.utc),
+                )
+            ],
+            1,
+        )
+
+    async def override_admin():
+        return admin
+
+    app.dependency_overrides[get_current_user] = override_admin
+    monkeypatch.setattr("app.api.audit_log.get_audit_logs", fake_get_audit_logs)
+    try:
+        with TestClient(app) as client:
+            response = client.get("/api/v1/audit-log?actor_kind=runner_token")
+        assert response.status_code == 200, response.text
+        data = response.json()
+        assert data["entries"][0]["details"]["project_id"] == "smoke-project"
+    finally:
+        app.dependency_overrides.pop(get_current_user, None)