vgi-python 0.8.0__tar.gz → 0.8.1__tar.gz

vgi_python-0.8.1/.github/dependabot.yml

@@ -0,0 +1,43 @@
+# Dependabot version updates. Security updates (PRs for flagged CVEs) are
+# enabled separately via the repo's "automated security fixes" setting; this
+# file governs the scheduled keep-current PRs.
+version: 2
+updates:
+  # Python dependencies (pyproject.toml + uv.lock).
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps"
+    # Roll all non-breaking bumps into a single weekly PR to keep noise down;
+    # major bumps still open as individual PRs so they get reviewed on their own.
+    groups:
+      python-minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+    ignore:
+      # aiohttp is transitive via vgi-rpc[external], which caps it at <3.14.
+      # The aiohttp CVE fixes only exist in >=3.14, so no bump is resolvable
+      # from this repo — the security updater errors out every run with
+      # "requirements are unsatisfiable". Ignore it here so Dependabot stops
+      # failing on an impossible update; the alerts stay visible in the
+      # security tab. The real fix is lifting the cap upstream in vgi-rpc.
+      - dependency-name: "aiohttp"
+
+  # GitHub Actions used by the workflows in .github/workflows/.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

vgi_python-0.8.1/.github/styles/config/vocabularies/VGI/accept.txt

@@ -0,0 +1,41 @@
+VGI
+vgi
+[Vv]gi-python
+[Vv]gi-rpc
+DuckDB
+Arrow
+[Aa]pache Arrow
+Haybarn
+pyarrow
+PyArrow
+RecordBatch
+RecordBatches
+mkdocstrings
+MkDocs
+uv
+uvx
+subprocess
+scalar
+[Aa]ggregations?
+[Dd]eserialize
+[Ss]erializable
+Diátaxis
+ATTACH
+classmethod
+dataclass
+runnable
+bool
+config
+[Mm]etadata
+namespace
+namespaces
+struct
+async
+stdin
+stdout
+optimizer
+[Pp]ushdown
+JWT
+HTTP
+OAuth
+TTL

{vgi_python-0.8.0 → vgi_python-0.8.1}/.github/workflows/ci.yml

@@ -3,8 +3,12 @@ name: CI
 on:
   push:
     branches: [main]
+    # README-only changes don't affect code, tests, or the mkdocs site
+    # (which is built from docs/, not README.md), so skip the full CI for them.
+    paths-ignore: ['README.md']
   pull_request:
     branches: [main]
+    paths-ignore: ['README.md']
   workflow_dispatch:
 
 # Least-privilege default for all jobs — none need write access. (The release
@@ -23,7 +27,7 @@ jobs:
         python-version: ["3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Install uv
         uses: astral-sh/setup-uv@v8.2.0
@@ -41,7 +45,7 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Install uv
         uses: astral-sh/setup-uv@v8.2.0
@@ -55,6 +59,9 @@ jobs:
       - name: Check linting
         run: uv run ruff check .
 
+      # Docstring consistency (pydoclint) runs inside the pytest suite via
+      # tests/test_docstrings.py, so it's not a separate CI lint step.
+
       - name: Type check (mypy)
         run: uv run mypy vgi/
 
@@ -65,6 +72,52 @@ jobs:
         run: uv run ty check vgi/
         continue-on-error: true
 
+  docs:
+    name: Docs (build + examples + prose)
+    runs-on: ubuntu-latest
+    env:
+      DISABLE_MKDOCS_2_WARNING: "true"
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --all-extras --group docs
+
+      - name: Install d2
+        run: curl -fsSL https://d2lang.com/install.sh | sh -s --
+
+      - name: Build docs (strict)
+        run: uv run mkdocs build --strict
+
+      - name: Test documentation examples
+        run: uv run pytest tests/test_documentation_examples.py tests/test_examples_workers.py -q
+
+      # Prose lint. Runs on every PR as a signal. Kept non-blocking for now:
+      # the Google package + spelling check needs a vocabulary-tuning pass
+      # against a real run before it can gate without false positives. Flip
+      # fail_on_error to true (and drop continue-on-error) once the vocab in
+      # .github/styles/config/vocabularies/VGI/accept.txt is settled.
+      - name: Prose lint (Vale)
+        uses: errata-ai/vale-action@v2
+        continue-on-error: true
+        with:
+          files: docs
+          fail_on_error: true
+
+      - name: Link check (lychee)
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # --root-dir resolves root-relative links (e.g. <img src="/assets/...">,
+          # which mkdocs serves from the site root = docs/) for offline checking.
+          args: "--no-progress --offline --root-dir ${{ github.workspace }}/docs docs/**/*.md *.md"
+          fail: true
+
   s3-offload-localstack:
     name: S3 Offload Tests (LocalStack)
     runs-on: ubuntu-latest
@@ -77,10 +130,10 @@ jobs:
           SERVICES: s3
           AWS_DEFAULT_REGION: us-east-1
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Checkout vgi-rpc
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           repository: Query-farm/vgi-rpc-python
           path: vgi-rpc

vgi_python-0.8.1/.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Docs
+
+# Cloudflare Pages deploy is disabled for now — docs hosting is moving to a
+# different approach. This workflow is manual-only (workflow_dispatch) and just
+# builds the site as a check; the CI workflow already validates the docs build
+# (strict), examples, prose, and links on every push. Re-add a deploy step here
+# (or a new workflow) once the new hosting path is decided.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Install d2
+        run: curl -fsSL https://d2lang.com/install.sh | sh -s --
+
+      - name: Build docs
+        run: uv run mkdocs build --strict

vgi_python-0.8.1/.github/workflows/integration.yml

@@ -0,0 +1,94 @@
+# Runs the canonical Query-farm/vgi integration sqllogictest suite against the
+# Python example worker on every push / PR. Rather than building the C++ extension
+# from source, it drives a prebuilt standalone `haybarn-unittest` and installs the
+# SIGNED vgi extension from the Haybarn community channel + its deps from core.
+# The .test files come from a pinned Query-farm/vgi checkout; ci/run-integration.sh
+# + ci/preprocess-require.awk adapt them for the standalone runner. See ci/README.md.
+#
+# (The separate ci.yml covers lint / type-check / unit + conformance tests / docs.
+# Those drive the pure-Python in-process Client; this workflow is the only place
+# the worker is exercised through the real published DuckDB extension over the wire.)
+name: Integration suite
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: integration-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # The Query-farm/vgi ref whose test/sql/integration suite we run. For now this
+  # tracks the latest `main` (resolved at checkout time) so the Python port is
+  # always validated against the newest C++ test suite. Pin to a specific commit
+  # SHA here if/when reproducible, deliberate bumps are wanted (see ci/README.md).
+  VGI_REF: main
+  # The Haybarn release providing the prebuilt haybarn-unittest binary. Must be
+  # ABI-compatible with the community-published vgi extension.
+  HAYBARN_RELEASE: haybarn-v1.5.4-rc1
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # stdio:  the subprocess transport (whole suite — the primary lane).
+          # shm:    stdio + the POSIX shared-memory side channel.
+          # launch: the AF_UNIX launcher-only tests.
+          # http:   the whole suite over the stateless HTTP transport.
+          - { lane: stdio }
+          - { lane: shm, shm_bytes: '67108864' }
+          - { lane: launch }
+          - { lane: http }
+    name: integration (${{ matrix.lane }})
+    steps:
+      - name: Checkout vgi-python
+        uses: actions/checkout@v6
+
+      - name: Checkout pinned vgi test suite
+        uses: actions/checkout@v6
+        with:
+          repository: Query-farm/vgi
+          ref: ${{ env.VGI_REF }}
+          path: vgi-upstream
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies (vgi + fixtures + all extras)
+        run: uv sync --all-extras --python 3.13
+
+      - name: Download haybarn-unittest
+        run: |
+          gh release download "$HAYBARN_RELEASE" \
+            --repo Query-farm-haybarn/haybarn \
+            --pattern 'haybarn_unittest-linux-amd64.zip' \
+            --output /tmp/haybarn-unittest.zip --clobber
+          unzip -o -q /tmp/haybarn-unittest.zip -d /tmp/haybarn-unittest
+          UNITTEST=$(find /tmp/haybarn-unittest -name 'haybarn-unittest' -type f | head -1)
+          chmod +x "$UNITTEST"
+          echo "HAYBARN_UNITTEST=$UNITTEST" >> "$GITHUB_ENV"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Run integration suite (${{ matrix.lane }})
+        run: ci/run-integration.sh
+        env:
+          VGI_SRC: ${{ github.workspace }}/vgi-upstream
+          TRANSPORT: ${{ matrix.lane }}
+          # Empty on every lane except shm; run-integration.sh drops an empty value.
+          VGI_RPC_SHM_SIZE_BYTES: ${{ matrix.shm_bytes || '' }}

{vgi_python-0.8.0 → vgi_python-0.8.1}/.github/workflows/release.yml

@@ -30,7 +30,7 @@ jobs:
     name: Build distributions
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Install uv
         uses: astral-sh/setup-uv@v8.2.0
@@ -45,13 +45,13 @@ jobs:
         run: uvx twine check dist-vgi/* dist-fixtures/*
 
       - name: Upload vgi artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist-vgi
           path: dist-vgi/
 
       - name: Upload vgi-fixtures artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist-fixtures
           path: dist-fixtures/
@@ -65,7 +65,7 @@ jobs:
       id-token: write # required for Trusted Publishing
     steps:
       - name: Download vgi artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist-vgi
           path: dist/
@@ -88,7 +88,7 @@ jobs:
       id-token: write # required for Trusted Publishing
     steps:
       - name: Download vgi-fixtures artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist-fixtures
           path: dist/

{vgi_python-0.8.0 → vgi_python-0.8.1}/.gitignore

@@ -6,6 +6,11 @@ dist/
 wheels/
 *.egg-info
 
+# MkDocs build output
+/site/
+# MkDocs plugin caches (d2 diagram render cache)
+/.cache/
+
 # Virtual environments
 .venv
 

vgi_python-0.8.1/.vale.ini

@@ -0,0 +1,19 @@
+# Vale prose-lint config for vgi-python docs.
+# Run locally with: vale docs/   (after `vale sync` to fetch the Google package)
+StylesPath = .github/styles
+
+# Only fail on errors. The Google package emits many style suggestions/warnings;
+# gating on those would be noisy, so the CI gate enforces error-level issues
+# (Vale core checks + spelling against the VGI vocabulary) only.
+MinAlertLevel = error
+
+Packages = Google
+
+Vocab = VGI
+
+[*.md]
+BasedOnStyles = Vale, Google
+
+# Snippet directives and our auto-generated API pages aren't prose to lint.
+[docs/api/*]
+BasedOnStyles =

vgi_python-0.8.1/DOCS_ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,122 @@
+# VGI-Python Documentation — Acceptance Criteria (review-ready v1)
+
+> Status: DRAFT for senior DX-engineer review. Derived from a requirements interview.
+> This document defines what "done and good" means for the documentation rework
+> before the site goes live at `vgi-python.query.farm`.
+
+## North Star
+
+**A developer who has never used VGI can build and run a real worker fast.**
+Everything on the site is optimized around that job-to-be-done; depth is available
+but never blocks the fast path.
+
+## Target audience (mixed — serve all via progressive disclosure)
+
+The reader could be a Python developer new to DuckDB/Arrow, a DuckDB/SQL user newer
+to Python, or someone fluent in both. Therefore:
+
+- The happy path is skimmable by experts (dense, copy-paste-ready).
+- Newcomers are served by **progressive disclosure**: inline "New to Arrow? →" /
+  "New to DuckDB extensions? →" callouts and links, not walls of prerequisite text.
+- We never assume knowledge silently; we either explain briefly or link out.
+
+## Information architecture — Diátaxis
+
+Top-level navigation is reorganized into the four Diátaxis modes (this directly
+addresses the current "hard to orient" problem):
+
+1. **Tutorial** — one guided, end-to-end "build your first worker" path.
+2. **How-to guides** — task-oriented recipes ("Add a table function", "Run over
+   HTTP with auth", "Persist aggregate state").
+3. **Concepts** — explanations: worker lifecycle (bind/init/process/finalize),
+   transports, the Arrow data model, catalogs & ATTACH, parallel workers.
+4. **API Reference** — the existing auto-generated mkdocstrings pages.
+
+The current 11 hand-written guides are **re-homed** into How-to vs Concepts (not
+left in a flat "Guides" bucket).
+
+## Scope
+
+### In scope for v1 (must be fully documented: tutorial coverage + how-to + runnable example)
+
+- **All four function patterns**: scalar, table, table-in-out, aggregate.
+- **Catalogs / ATTACH model** — how functions are surfaced to DuckDB.
+- **State storage** — `FunctionStorage` backends for stateful/aggregate functions.
+- **Auth + HTTP transport** — running a worker over HTTP with bearer/JWT auth.
+- **Filter pushdown & column statistics** — optimizer integration for table functions.
+
+### Out of scope for v1 (reference-only / deferred — must NOT block launch)
+
+- Transactor (transactional DB access)
+- External storage / large-payload offload (S3/GCS)
+- Observability (OpenTelemetry / Sentry)
+- Sharding / meta-worker, cross-language client codegen, standalone secret service
+
+These remain available in the auto-generated API reference but get no tutorial/how-to
+investment in v1.
+
+## Headline acceptance test (Time-To-First-Success)
+
+> **An unfamiliar developer, working unaided from the docs, has both a custom
+> scalar function AND a custom table function callable from DuckDB within
+> ≤20 minutes.**
+
+- "Callable from DuckDB" = `SELECT my_cat.my_scalar(col) FROM t` returns rows, and
+  `SELECT * FROM my_cat.my_table(args)` returns rows.
+- Engine for the timed path: **Haybarn** (`uvx haybarn-cli`) as the primary happy
+  path; a stock-DuckDB variant (`INSTALL vgi FROM community; LOAD vgi;`) shown in a
+  callout/tab for portability.
+- Every place a test participant gets stuck is logged and fixed before sign-off.
+
+## Per-page orientation standard (applies to every tutorial / how-to / concept page)
+
+Each page must contain:
+
+1. **Lead "what + who" line** — one sentence at the top: what this page is and who
+   it's for (reader self-orients in <10 s).
+2. **Prerequisites stated** — explicit assumed knowledge, prior steps, and required
+   extras (`vgi-python[http]`, etc.), with links.
+3. **At least one complete, runnable example** — no elisions; covered by the CI
+   example tests (see Quality Gates).
+4. **"Next steps" links** — a closing section pointing to the logical next page(s);
+   no dead ends.
+
+## Example correctness bar
+
+- **100% of Python code blocks are copy-paste runnable and CI-tested** (e.g. via
+  `pytest-examples`, already a dev dependency).
+- The tutorial worker is **built and queried end-to-end in an automated test**.
+- A broken example fails the build.
+
+## Quality gates (all three required to sign off v1)
+
+1. **Fresh-dev usability test** — ≥1 developer unfamiliar with VGI completes the
+   headline acceptance test (scalar + table from DuckDB, ≤20 min, unaided). All
+   stumbling points resolved.
+2. **Senior DX reviewer rubric** — named senior DX engineer(s) score the site
+   against a written checklist: orientation, scannability, completeness vs the
+   in-scope list, correctness, navigation, and the per-page standard above. All
+   must-fix items resolved before merge.
+3. **Automated quality gates in CI**:
+   - `mkdocs build --strict` passes with zero warnings (no broken links / refs).
+   - All documentation examples execute successfully.
+   - Link check + prose/style lint pass.
+
+## Definition of Done (v1)
+
+- [ ] Diátaxis nav live (Tutorial / How-to / Concepts / API Reference); existing
+      guides re-homed.
+- [ ] Guided tutorial takes a reader from zero → scalar + table function queried
+      from Haybarn, with the stock-DuckDB variant noted.
+- [ ] How-to + runnable example exists for each in-scope topic (4 patterns +
+      catalogs + state storage + auth/HTTP + pushdown/stats).
+- [ ] Concept pages cover lifecycle, transports, Arrow model, catalogs, parallelism.
+- [ ] Every page meets the 4-point orientation standard.
+- [ ] All examples runnable and CI-tested; tutorial validated end-to-end in CI.
+- [ ] Out-of-scope topics confined to reference; not advertised as v1 guides.
+- [ ] All three quality gates passed and signed off.
+
+## Open items to confirm with reviewers
+
+- Named senior DX reviewer(s) and the recruited fresh-dev test participant.
+- Final wording/threshold of the prose-style lint (e.g. Vale ruleset), if adopted.

vgi_python-0.8.1/DOCS_REVIEW_RUBRIC.md

@@ -0,0 +1,67 @@
+# vgi-python docs — senior DX review rubric
+
+> Status: review checklist for the review-ready v1 of the documentation
+> (see `DOCS_ACCEPTANCE_CRITERIA.md`). A reviewer scores each item Pass / Fix /
+> N/A. Every **Fix** must be resolved (or explicitly waived) before the site
+> goes live at `vgi-python.query.farm`.
+
+Reviewer: ________________   Date: ________________   Commit: ________________
+
+## 1. Orientation (the problem this rework targets)
+
+- [ ] The home page makes it obvious in <10 s what vgi-python is and where to start.
+- [ ] Top-level nav clearly separates **Tutorial / How-to / Concepts / API Reference**
+      (Diátaxis); a newcomer can tell which to open for their need.
+- [ ] Every tutorial/how-to/concept page opens with a **"what + who"** line.
+- [ ] No page is a dead end — each ends with **"Next steps"** links.
+
+## 2. The fast path (job-to-be-done: ship a worker fast)
+
+- [ ] The tutorial gets a reader from zero → a **scalar + table** function callable from
+      DuckDB, and is realistically completable in **≤20 minutes**.
+- [ ] The first step yields a working query quickly (scalar before table).
+- [ ] Haybarn is the primary path; the stock-DuckDB variant is present and correct.
+- [ ] Copy-paste works: the worker shown is complete and runnable as-is.
+
+## 3. Completeness vs. the in-scope list
+
+- [ ] All four function patterns are documented with a runnable example: scalar, table,
+      table-in-out, aggregate.
+- [ ] Catalogs / ATTACH, state storage, auth + HTTP, and filter pushdown & stats each have a
+      how-to.
+- [ ] Out-of-scope topics (transactor, external storage, observability, sharding/codegen/secret
+      service) are reference-only and not advertised as v1 guides.
+
+## 4. Correctness
+
+- [ ] Every code example is accurate and runs (CI: `test_documentation_examples.py` +
+      `test_examples_workers.py` green).
+- [ ] SQL snippets use correct catalog/function names and match the worker shown.
+- [ ] Conceptual claims (lifecycle phases, transports, Arrow semantics) are accurate.
+- [ ] API reference renders for every in-scope module (CI: `mkdocs build --strict` green).
+
+## 5. Scannability & progressive disclosure
+
+- [ ] Pages use headings, tables, and short paragraphs; an expert can skim.
+- [ ] Newcomer background is in collapsible callouts, not blocking the main flow.
+- [ ] Prerequisites and required extras (`[http]`, `[oauth]`, …) are stated where needed.
+
+## 6. Navigation & polish
+
+- [ ] No broken links (CI: lychee + strict build green).
+- [ ] Search returns sensible results for common terms (worker, scalar, aggregate, ATTACH).
+- [ ] Light/dark themes, logo, and code-copy all work.
+
+## Automated gates (must be green at review time)
+
+- [ ] `mkdocs build --strict` — zero warnings
+- [ ] `pytest tests/test_documentation_examples.py tests/test_examples_workers.py`
+- [ ] lychee link-check
+- [ ] Vale prose lint (advisory until vocab is tuned; note residual warnings)
+
+## Sign-off
+
+- [ ] All **Fix** items resolved or waived (waivers noted below).
+- [ ] Fresh-dev usability test passed (see `DOCS_USABILITY_TEST.md`).
+
+Waivers / notes:

vgi_python-0.8.1/DOCS_USABILITY_TEST.md

@@ -0,0 +1,71 @@
+# vgi-python docs — fresh-dev usability test
+
+> The headline acceptance gate: an unfamiliar developer, working **only** from the
+> docs, builds and runs a worker. This protocol scripts that test and captures
+> what to fix. See `DOCS_ACCEPTANCE_CRITERIA.md` for the full criteria.
+
+## Goal (pass condition)
+
+> A developer **new to VGI**, working **unaided** from the published docs, reaches a custom
+> **scalar AND table** function callable from DuckDB in **≤20 minutes**.
+
+"Callable from DuckDB" means both:
+
+- `SELECT greetings.greeting('Alice')` returns `Hello, Alice!`, and
+- `SELECT * FROM greetings.greeting_series(3)` returns 3 rows.
+
+## Participant criteria
+
+- Comfortable writing Python; **has not** used VGI before.
+- A mix is ideal across runs: at least one participant new to DuckDB extensions, and at least
+  one new to Apache Arrow (this is the "serve all" audience we're validating).
+- Has Python 3.13+ and `uv` installed (or we install them first, off the clock).
+
+## Facilitator rules
+
+- **Do not help.** Point the participant at the docs home page and the timer; then observe in
+  silence. Answer only "I can't help with that — what would you try?"
+- Record the clock at each milestone and **every** point of confusion verbatim.
+- Capture the participant's words ("I don't know what a catalog is here") — those become doc fixes.
+
+## Script
+
+1. Start screen recording (or take notes) and the timer.
+2. Give the participant only this: *"Using the vgi-python docs, build a worker that adds two
+   functions to DuckDB — one that greets a name, and one that generates a series of greetings —
+   and run both from SQL. Start at the docs home page."*
+3. Observe until success or 30 minutes elapsed (let them run past 20 so we learn where the tail is).
+4. Debrief: what was confusing, what was missing, what they expected to find and didn't.
+
+## Milestones (record the time reached)
+
+| Milestone | Time | Notes |
+|---|---|---|
+| Found the tutorial / starting point | | |
+| Worker file written | | |
+| SQL engine launched (Haybarn or DuckDB) | | |
+| Worker attached (`ATTACH …`) | | |
+| **Scalar query returned a result** | | |
+| **Table query returned rows** | | |
+| Total time to success (or DNF) | | |
+
+## Stumble log
+
+| # | Where (page / step) | What happened | Severity (block/slow/nit) | Fix |
+|---|---|---|---|---|
+| 1 | | | | |
+| 2 | | | | |
+| 3 | | | | |
+
+## Outcome
+
+- [ ] Passed (≤20 min, unaided, both functions) — participant: ____________  time: ______
+- [ ] Did not pass — root cause: ____________________________________________
+
+**Every block/slow stumble must produce a doc fix (or an explicit waiver) before sign-off.**
+
+## Runs
+
+| Date | Participant background | Result | Time | Fixes filed |
+|---|---|---|---|---|
+| | | | | |