Implement external-results case endpoints with test-case auto-upsert, transition enforcement, and traceability linking

.github/dependabot.yml

@@ -12,6 +12,13 @@ updates:
     commit-message:
       prefix: "chore(deps)"
     open-pull-requests-limit: 10
+    groups:
+      python-patch-minor:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
 
   # NPM dependencies (frontend)
   - package-ecosystem: "npm"
@@ -25,6 +32,13 @@ updates:
     commit-message:
       prefix: "chore(deps)"
     open-pull-requests-limit: 10
+    groups:
+      npm-patch-minor:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
 
   # Docker dependencies
   - package-ecosystem: "docker"
@@ -38,6 +52,13 @@ updates:
     commit-message:
       prefix: "chore(deps)"
     open-pull-requests-limit: 10
+    groups:
+      docker-patch-minor:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
 
   # GitHub Actions
   - package-ecosystem: "github-actions"
@@ -51,3 +72,10 @@ updates:
     commit-message:
       prefix: "chore(ci)"
     open-pull-requests-limit: 10
+    groups:
+      actions-patch-minor:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"

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

@@ -0,0 +1,147 @@
+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'
+      - 'scripts/smoke/**'
+  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: 942416538dc5d9a23895c9f601e4e4f2d152e7e5
+          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/i8j9k0l1m2n3_audit_log_actor_kind.py

@@ -0,0 +1,58 @@
+"""add actor_kind and actor_token_id to audit_log
+
+Revision ID: i8j9k0l1m2n3
+Revises: h7i8j9k0l1m2
+Create Date: 2026-05-07 14:30:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "i8j9k0l1m2n3"
+down_revision: Union[str, None] = "h7i8j9k0l1m2"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("audit_log", sa.Column("actor_kind", sa.String(length=20), nullable=False, server_default="user"))
+    op.add_column("audit_log", sa.Column("actor_token_id", postgresql.UUID(as_uuid=True), nullable=True))
+    op.alter_column("audit_log", "user_id", existing_type=postgresql.UUID(as_uuid=True), nullable=True)
+
+    op.execute("UPDATE audit_log SET actor_kind = 'user' WHERE actor_kind IS NULL")
+
+    op.create_foreign_key(
+        "fk_audit_log_actor_token_id_runner_tokens",
+        "audit_log",
+        "runner_tokens",
+        ["actor_token_id"],
+        ["id"],
+        ondelete="SET NULL",
+    )
+    op.create_check_constraint(
+        "ck_audit_log_actor_identity",
+        "audit_log",
+        "(actor_kind = 'user' AND user_id IS NOT NULL AND actor_token_id IS NULL) "
+        "OR (actor_kind = 'runner_token' AND actor_token_id IS NOT NULL AND user_id IS NULL)",
+    )
+    op.create_index("idx_audit_log_actor_token_id", "audit_log", ["actor_token_id"])
+    op.create_index("idx_audit_log_actor_kind_created_at", "audit_log", ["actor_kind", "created_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("idx_audit_log_actor_kind_created_at", table_name="audit_log")
+    op.drop_index("idx_audit_log_actor_token_id", table_name="audit_log")
+    op.drop_constraint("ck_audit_log_actor_identity", "audit_log", type_="check")
+    op.drop_constraint("fk_audit_log_actor_token_id_runner_tokens", "audit_log", type_="foreignkey")
+
+    # Restore non-null user_id invariant for pre-actor rows.
+    op.execute("DELETE FROM audit_log WHERE user_id IS NULL")
+    op.alter_column("audit_log", "user_id", existing_type=postgresql.UUID(as_uuid=True), nullable=False)
+    op.drop_column("audit_log", "actor_token_id")
+    op.drop_column("audit_log", "actor_kind")

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)