Merge pull request #16 from WebFirstLanguage/codex/wfl-orm-migrations

feat(database): add a WFL ORM and audited SQLite migrations

Author: logbie

.github/workflows/governance.yml

@@ -26,7 +26,7 @@ jobs:
           - os: windows-latest
             runner: windows-latest
     runs-on: ${{ matrix.runner }}
-    timeout-minutes: 10
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
         with:
@@ -35,7 +35,67 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'
+      - name: Provision the current WFL nightly
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          # The GitHub daily release is an immutable mirror. The canonical
+          # publisher can release a newer runtime on the same day to this CDN.
+          $cdn = 'https://wfl.nyc3.cdn.digitaloceanspaces.com'
+          # A previously cached pointer can retain the CDN's older one-hour TTL.
+          $publicationUri = "$cdn/status.json?request=$([guid]::NewGuid().ToString('N'))"
+          $publication = Invoke-RestMethod -Uri $publicationUri
+          if ($publication.result -ne 'success' -or $publication.branch -ne 'main' -or
+              $publication.version -notmatch '^\d+\.\d+\.\d+$' -or
+              $publication.sha -notmatch '^[a-f0-9]{40}$') {
+            throw 'Invalid official WFL publication record'
+          }
+          $releaseVersion = [regex]::Escape($publication.version)
+          $pattern = if ($IsWindows) { "^wfl-$releaseVersion\.msi$" } else { "^wfl-$releaseVersion-linux-x86_64-[a-f0-9]{7,40}\.tar\.gz$" }
+          $assets = @($publication.message -split '\s+' | Where-Object { $_ -match $pattern })
+          if ($assets.Count -ne 1) { throw 'Publication must name one immutable platform-specific WFL asset' }
+          $assetName = $assets[0]
+          if (-not $IsWindows -and $assetName -match '-linux-x86_64-([a-f0-9]{7,40})\.tar\.gz$') {
+            if (-not $publication.sha.StartsWith($Matches[1])) { throw 'WFL artifact revision does not match publication' }
+          }
+          $assetUrl = "$cdn/releases/$assetName"
+          $checksum = (Invoke-WebRequest -Uri "$assetUrl.sha256").Content.Trim()
+          $checksumPattern = '^([a-fA-F0-9]{64})\s+\*?' + [regex]::Escape($assetName) + '$'
+          if ($checksum -notmatch $checksumPattern) { throw 'Invalid immutable WFL checksum sidecar' }
+          $expectedDigest = $Matches[1].ToLowerInvariant()
+          $runtimeRoot = Join-Path $env:RUNNER_TEMP 'scriptorium-wfl'
+          New-Item -ItemType Directory -Path $runtimeRoot -Force | Out-Null
+          $archive = Join-Path $runtimeRoot $assetName
+          Invoke-WebRequest -Uri $assetUrl -OutFile $archive
+          $digest = (Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash.ToLowerInvariant()
+          if ($expectedDigest -ne $digest) { throw 'WFL release asset digest mismatch' }
+          if ($IsWindows) {
+            $expanded = Join-Path $runtimeRoot 'expanded'
+            $arguments = @('/a', "`"$archive`"", '/qn', "TARGETDIR=`"$expanded`"")
+            $installer = Start-Process msiexec.exe -ArgumentList $arguments -Wait -PassThru -WindowStyle Hidden
+            if ($installer.ExitCode -ne 0) { throw "WFL extraction failed: $($installer.ExitCode)" }
+            $programs = @(Get-ChildItem -LiteralPath $expanded -Filter wfl.exe -File -Recurse)
+          } else {
+            tar -xzf $archive -C $runtimeRoot
+            if ($LASTEXITCODE -ne 0) { throw 'WFL extraction failed' }
+            $programs = @(Get-ChildItem -LiteralPath $runtimeRoot -Filter wfl -File -Recurse)
+          }
+          if ($programs.Count -ne 1) { throw 'Expected one extracted WFL executable' }
+          $runtimePath = $programs[0].FullName
+          $programs[0].DirectoryName | Out-File -FilePath $env:GITHUB_PATH -Append
+          $version = & $runtimePath --version
+          if ($LASTEXITCODE -ne 0) { throw 'Extracted WFL runtime did not start' }
+          if ($version -ne "WebFirst Language (WFL) version $($publication.version)") { throw 'WFL executable version does not match publication' }
+          @(
+            '### Governance runtime',
+            "- Publication: $cdn/status.json",
+            "- WFL revision: $($publication.sha)",
+            "- Asset: $assetUrl",
+            "- SHA256: $digest",
+            "- Runtime: $version",
+            "- Scriptorium: $env:GITHUB_SHA"
+          ) | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append
       - name: Test repository tooling
-        run: python -m unittest discover -s tests/tooling -v
+        run: wfl scripts/run_tests.wfl --group tooling
       - name: Check repository hygiene
         run: python scripts/check_repo_hygiene.py

.github/workflows/runtime-capabilities.yml

@@ -0,0 +1,92 @@
+name: WFL ORM capability gates
+
+on:
+  push:
+    branches: [codex/wfl-orm-migrations]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: orm-capabilities-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  runtime:
+    name: Resolve current nightly
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    timeout-minutes: 5
+    outputs:
+      image: ${{ steps.runtime.outputs.image }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Pull nightly and record provenance
+        id: runtime
+        shell: bash
+        run: |
+          docker pull bsbyrdwfl/wfl:nightly
+          image="$(docker image inspect --format '{{index .RepoDigests 0}}' bsbyrdwfl/wfl:nightly)"
+          echo "image=$image" >> "$GITHUB_OUTPUT"
+          version="$(docker run --rm --network none "$image" --version)"
+          {
+            echo '### ORM prerequisite evidence (not completed ORM validation)'
+            echo "- Image: $image"
+            echo "- Runtime: $version"
+            echo "- Scriptorium: $(git rev-parse HEAD)"
+            echo "- Scribe: $(git -C lib/scribe rev-parse HEAD)"
+            echo '- Every probe, fixture, HTTP driver and assertion is WFL.'
+            echo '- Unmet capability assertions fail their jobs without suppression.'
+          } | tee -a "$GITHUB_STEP_SUMMARY"
+
+  probes:
+    name: ${{ matrix.suite }}
+    needs: runtime
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    timeout-minutes: 5
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - suite: orm-native-baseline
+            path: tests/runtime/orm-native-baseline.test.wfl
+          - suite: transaction-validation-capability
+            path: tests/runtime/transaction-validation-capability.test.wfl
+          - suite: rebuild-foreign-keys-capability
+            path: tests/runtime/rebuild-foreign-keys-capability.test.wfl
+          - suite: process-capabilities
+            path: tests/runtime/process-capabilities.test.wfl
+          - suite: http-redirect-capability
+            path: tests/runtime/http-redirect-capability.test.wfl
+          - suite: media-body-limit
+            path: tests/integration/media.test.wfl
+    env:
+      RESOLVED_IMAGE: ${{ needs.runtime.outputs.image }}
+      PROBE_SUITE: ${{ matrix.path }}
+      TEST_CONTAINER: scriptorium-probe-${{ github.run_id }}-${{ github.run_attempt }}-${{ strategy.job-index }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Invoke WFL capability suite
+        shell: bash
+        run: |
+          docker pull "$RESOLVED_IMAGE"
+          docker run --rm --init --name "$TEST_CONTAINER" \
+            --user 0:0 --entrypoint /bin/sh \
+            --mount "type=bind,source=$GITHUB_WORKSPACE,target=/source,readonly" \
+            --env PROBE_SUITE --workdir /work "$RESOLVED_IMAGE" -ec '
+              cp -a /source/. /work/
+              exec wfl --test "$PROBE_SUITE"
+            '
+      - name: Clean up disposable container
+        if: always()
+        shell: bash
+        run: |
+          if docker container inspect "$TEST_CONTAINER" >/dev/null 2>&1; then
+            docker container rm --force "$TEST_CONTAINER"
+          fi

.github/workflows/update-scribe.yml

@@ -136,8 +136,8 @@ jobs:
             echo
             echo '| Check or exact command | Result and evidence |'
             echo '|---|---|'
-            echo '| `python3 scripts/run_tests.py --include-scribe` | Pending — this workflow prepares the dependency bump. Link WFL tests results for the current revision, including the nightly image digest and runtime version; record failures. |'
-            echo '| `python -m unittest discover -s tests/tooling -v` | Pending — Governance results are not verified by this workflow. Link results for the current revision. |'
+            echo '| `wfl --execution-timeout 1200 scripts/run_tests.wfl` | Pending — this workflow prepares the dependency bump. Link WFL tests results for the current revision, including the nightly image digest and runtime version; record failures. |'
+            echo '| `wfl scripts/run_tests.wfl --group tooling` | Pending — Governance results are not verified by this workflow. Link results for the current revision. |'
             echo '| `python scripts/check_repo_hygiene.py` | Pending — Governance results are not verified by this workflow. Link results for the current revision. |'
             echo '| Affected HTTP/UI rendering journeys | Not run — upstream diff review is needed to identify affected paths. Record setup, expected/actual outcome, and evidence. |'
             echo

.github/workflows/wfl-tests.yml

@@ -18,7 +18,7 @@ jobs:
   wfl-tests:
     name: WFL nightly (Blacksmith)
     runs-on: blacksmith-2vcpu-ubuntu-2404
-    timeout-minutes: 15
+    timeout-minutes: 30
     env:
       WFL_IMAGE: bsbyrdwfl/wfl:nightly
       TEST_CONTAINER: scriptorium-tests-${{ github.run_id }}-${{ github.run_attempt }}
@@ -36,36 +36,40 @@ jobs:
           image="$(docker image inspect --format '{{index .RepoDigests 0}}' "$WFL_IMAGE")"
           echo "image=$image" >> "$GITHUB_OUTPUT"
           version="$(docker run --rm --network none "$image" --version)"
+          runtime_revision="$(docker image inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' "$image")"
+          [[ "$runtime_revision" =~ ^[a-f0-9]{40}$ ]] || { echo 'Official image is missing its WFL source revision'; exit 1; }
           {
             echo '### WFL nightly test environment'
             echo
             echo "- Image: $image"
             echo "- Runtime: $version"
+            echo "- WFL revision: $runtime_revision"
             echo "- Scriptorium: $(git rev-parse HEAD)"
             echo "- Scribe: $(git -C lib/scribe rev-parse HEAD)"
             echo '- Runner: blacksmith-2vcpu-ubuntu-2404 (Linux x64)'
-            echo '- Command: python3 scripts/run_tests.py --include-scribe'
-            echo '- HTTP checks: python3 -m unittest discover -s tests/integration -v'
+            echo '- Command: wfl --execution-timeout 1200 scripts/run_tests.wfl'
+            echo '- Coverage: application, ORM/migrations/recovery, HTTP integration, tooling, examples, pinned Scribe'
           } | tee -a "$GITHUB_STEP_SUMMARY"
 
-      - name: Run WFL suites and HTTP configuration checks
+      - name: Run the complete WFL suite
         shell: bash
         env:
           RESOLVED_IMAGE: ${{ steps.runtime.outputs.image }}
         run: |
           # The published image is a minimal runtime with a WFL entrypoint.
-          # Install Python only in this disposable container. Scribe fixtures
-          # go to its temporary directory; the checkout stays read-only.
+          # Python is only the implementation of the repository hygiene checker.
+          # Every scenario, fixture, assertion and test driver is WFL. A writable
+          # disposable copy keeps synthetic databases/Git indexes off the checkout.
           docker run --rm --init --name "$TEST_CONTAINER" \
             --user 0:0 --entrypoint /bin/sh \
-            --mount "type=bind,source=$GITHUB_WORKSPACE,target=/work,readonly" \
+            --mount "type=bind,source=$GITHUB_WORKSPACE,target=/source,readonly" \
             --workdir /work "$RESOLVED_IMAGE" -ec '
               apt-get update
-              apt-get install --yes --no-install-recommends python3
+              apt-get install --yes --no-install-recommends python3 python-is-python3 git
+              cp -a /source/. /work/
               python3 --version
               wfl --version
-              python3 scripts/run_tests.py --include-scribe
-              python3 -m unittest discover -s tests/integration -v
+              wfl --execution-timeout 1200 scripts/run_tests.wfl
             '
 
       - name: Clean up test container

.repo-hygiene.toml

@@ -10,7 +10,7 @@ allowed-files = [
   "REPOSITORY_HYGIENE.md", "SECURITY.md", "main.wfl", "testing.md",
 ]
 allowed-dirs = [
-  ".github", "admin", "app", "docs", "lib", "scripts", "static",
+  ".github", "admin", "app", "docs", "examples", "lib", "scripts", "static",
   "TestPrograms", "tests", "themes",
 ]
 
@@ -21,8 +21,9 @@ files = [
   "CONTRIBUTING.md", "GOVERNANCE.md", "LICENSE", "README.md",
   "REPOSITORY_HYGIENE.md", "SECURITY.md", "main.wfl", "testing.md",
   "docs/ARCHITECTURE.md", "docs/PROJECT-LAYOUT.md", "docs/THEMING.md",
-  "scripts/check_repo_hygiene.py", "scripts/run_tests.py",
-  "tests/tooling/test_repo_hygiene.py", "tests/tooling/test_run_tests.py",
+  "scripts/check_repo_hygiene.py", "scripts/run_tests.wfl",
+  "scripts/test_support.wfl", "scripts/resolve_runtime.wfl", "scripts/.wflcfg",
+  "tests/tooling/hygiene.test.wfl", "tests/tooling/runner.test.wfl", "tests/tooling/.wflcfg",
   ".github/pull_request_template.md", ".github/workflows/governance.yml",
 ]
 # These paths must remain Git gitlinks; their contents are upstream-owned.

.wflcfg

@@ -1,6 +1,6 @@
 # Scriptorium configuration (WFL runtime and application settings)
 timeout_seconds = 60
-logging_enabled = false
+execution_logging = false
 debug_report_enabled = false
 log_level = info
 

CLAUDE.md

@@ -74,14 +74,17 @@ violate the standard.
 - **Scribe is a submodule.** Don't edit `lib/scribe/` in place; changes go
   upstream to WebFirstLanguage/Scribe, then bump via
   `scripts/update-scribe.sh`.
-- **Checks:** `python scripts/run_tests.py` runs every Scriptorium WFL suite;
-  add `--include-scribe` for dependency updates. Run
-  `python -m unittest discover -s tests/tooling -v` and
-  `python scripts/check_repo_hygiene.py` for repository tooling and hygiene.
-  Python 3.11+ is needed for tooling; `wfl` is needed for application tests.
-  The Governance workflow runs tooling tests and hygiene on Blacksmith Linux
-  and GitHub-hosted Windows. The WFL tests workflow runs the application and
-  pinned Scribe suites on Blacksmith using a freshly pulled `bsbyrdwfl/wfl:nightly` image;
+- **Checks:** `wfl --execution-timeout 1200 scripts/run_tests.wfl` runs the complete suite: application,
+  ORM/migrations/recovery, HTTP integration, tooling, executable examples, and
+  pinned Scribe. `--group tooling` or `--group application` selects a focused
+  run. Run `python scripts/check_repo_hygiene.py` for the repository hygiene gate.
+  Every test, fixture, assertion, helper and driver is WFL. Python 3.11+ and Git
+  are required only for the hygiene checker's implementation subject. The runner
+  uses the WFL executable that launched it, with an optional `--wfl` override.
+  It needs the owned-process completion and `current_executable` runtime APIs.
+  Governance provisions WFL and runs tooling and hygiene on Blacksmith Linux
+  and GitHub-hosted Windows. WFL tests runs the complete suite on Blacksmith
+  using a freshly pulled `bsbyrdwfl/wfl:nightly` image;
   its summary records the resolved image digest, runtime version, and source
   revisions. See
   [testing.md](testing.md) for commands, coverage limits, and merge evidence.

CONTRIBUTING.md

@@ -55,7 +55,7 @@ the baseline suites:
 
 ```sh
 wfl --version
-python scripts/run_tests.py
+wfl --execution-timeout 1200 scripts/run_tests.wfl
 ```
 
 Use `--wfl /absolute/path/to/wfl` if the interpreter is not on `PATH`; use
@@ -106,17 +106,16 @@ the PR:
 
 ```sh
 python scripts/check_repo_hygiene.py
-python -m unittest discover -s tests/tooling -v
-python scripts/run_tests.py
+wfl --execution-timeout 1200 scripts/run_tests.wfl
 ```
 
-For a Scribe pin, rendering, or template-engine integration change, also run:
+The complete command includes pinned Scribe. For a focused Scribe check, run:
 
 ```sh
-python scripts/run_tests.py --include-scribe
+wfl scripts/run_tests.wfl --group scribe
 ```
 
-The extra suite runs the pinned Scribe tests in a temporary copy because they
+The Scribe group runs the pinned tests in a temporary copy because they
 write fixtures. Follow [testing.md](testing.md) for HTTP, UI, security, migration,
 and recovery checks triggered by the change. Prose-only changes need relevant
 link, command, and hygiene checks; they do not need invented application tests.