crucible-emulator 0.1.0a2__tar.gz

crucible_emulator-0.1.0a2/.dockerignore

@@ -0,0 +1,16 @@
+.local
+.venv
+.git
+.github
+.claude
+**/__pycache__
+**/*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+dist
+build
+**/*.egg-info
+tests
+corpus
+examples

crucible_emulator-0.1.0a2/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @CallumWalterWhite

crucible_emulator-0.1.0a2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,43 @@
+name: Bug report
+description: Crucible returns a different result or error than real BigQuery, or crashes.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Please do not include credentials, project IDs or private data.
+        For an "unsupported" error, use the "Unsupported feature" template instead.
+  - type: textarea
+    id: query
+    attributes:
+      label: Query or request
+      description: The smallest SQL (or API call) that shows the problem, with any CREATE TABLE / INSERT it needs.
+      render: sql
+    validations:
+      required: true
+  - type: textarea
+    id: bigquery
+    attributes:
+      label: What real BigQuery returns
+      description: Rows, types or the exact error message. Say if you have not checked against BigQuery.
+    validations:
+      required: true
+  - type: textarea
+    id: crucible
+    attributes:
+      label: What Crucible returns
+      description: Rows, types or the exact error message.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Crucible version
+      description: The Docker tag or `pip show crucible-emulator` version, or the commit if built from source.
+    validations:
+      required: true
+  - type: input
+    id: client
+    attributes:
+      label: Client and version
+      description: For example google-cloud-bigquery 3.46.1, dbt-core 1.12.6 with dbt-bigquery 1.12.1, or curl.

crucible_emulator-0.1.0a2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/CallumWalterWhite/crucible/blob/main/SECURITY.md
+    about: Report vulnerabilities privately as described in SECURITY.md, not in a public issue.

crucible_emulator-0.1.0a2/.github/ISSUE_TEMPLATE/unsupported_feature.yml

@@ -0,0 +1,33 @@
+name: Unsupported feature
+description: Crucible answers "Not supported by Crucible" for something you need.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please do not include credentials, project IDs or private data.
+  - type: input
+    id: message
+    attributes:
+      label: Error message
+      description: The full "Not supported by Crucible ..." message.
+    validations:
+      required: true
+  - type: textarea
+    id: query
+    attributes:
+      label: Query or request
+      description: The smallest SQL (or API call) that triggers it.
+      render: sql
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What real BigQuery returns
+      description: The rows or result you expect, if you know them.
+  - type: textarea
+    id: context
+    attributes:
+      label: Where you hit it
+      description: For example a dbt package or macro, a client method, or your own SQL.

crucible_emulator-0.1.0a2/.github/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+  - package-ecosystem: "docker"
+    directory: "/docker"
+    schedule:
+      interval: "weekly"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"

crucible_emulator-0.1.0a2/.github/workflows/ci.yml

@@ -0,0 +1,194 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - run: uv sync --locked --all-extras --group dev
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run pyright
+      - run: uv run lint-imports
+
+  corpus-guard:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Only corpus-record/ branches may set verified true (ADR 0013)
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: scripts/check-corpus-verified.sh "$BASE_SHA" "$HEAD_REF"
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - run: uv sync --locked --all-extras --python ${{ matrix.python }}
+      - run: uv run pytest
+
+  docker:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+      - name: Build image
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: docker/Dockerfile
+          tags: crucible:ci
+          load: true
+          push: false
+      - name: Start emulators and wait for health
+        run: |
+          wait_for_health() {  # <container> <port>
+            for _ in $(seq 60); do
+              if curl -fsS --max-time 2 "http://127.0.0.1:$2/_crucible/health" >/dev/null; then
+                echo "$1 healthy on port $2"
+                return 0
+              fi
+              sleep 1
+            done
+            echo "$1 not healthy after 60s" >&2
+            docker logs "$1" >&2 || true
+            return 1
+          }
+          # The image sets CRUCIBLE_HOST=0.0.0.0, so the server listens on all container interfaces.
+          docker run -d --name crucible-bigquery -p 127.0.0.1:9050:9050 \
+            crucible:ci serve --dialect bigquery --port 9050
+          docker run -d --name crucible-snowflake -p 127.0.0.1:8080:8080 \
+            crucible:ci serve --dialect snowflake --port 8080
+          wait_for_health crucible-bigquery 9050
+          wait_for_health crucible-snowflake 8080
+
+  clients:
+    needs: docker
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - dialect: bigquery
+            port: 9050
+            client: google-cloud-bigquery==3.27.0
+          - dialect: bigquery
+            port: 9050
+            client: google-cloud-bigquery
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+      - name: Build image
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: docker/Dockerfile
+          tags: crucible:ci
+          load: true
+          push: false
+      - name: Start emulator and wait for health
+        env:
+          DIALECT: ${{ matrix.dialect }}
+          PORT: ${{ matrix.port }}
+        run: |
+          docker run -d --name crucible -p "127.0.0.1:${PORT}:${PORT}" \
+            crucible:ci serve --dialect "$DIALECT" --port "$PORT"
+          for _ in $(seq 60); do
+            if curl -fsS --max-time 2 "http://127.0.0.1:${PORT}/_crucible/health" >/dev/null; then
+              echo "healthy on port ${PORT}"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "not healthy after 60s" >&2
+          docker logs crucible >&2 || true
+          exit 1
+      - name: Run official client tests
+        env:
+          CLIENT_SPEC: ${{ matrix.client }}
+          DIALECT: ${{ matrix.dialect }}
+          CRUCIBLE_URL: http://127.0.0.1:${{ matrix.port }}
+        run: uv run --with "$CLIENT_SPEC" pytest -m clients tests/clients -k "$DIALECT"
+
+  dbt:
+    needs: docker
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - dialect: bigquery
+            port: 9050
+            core: dbt-core==1.9.11
+            adapter: dbt-bigquery==1.9.0
+          - dialect: bigquery
+            port: 9050
+            core: dbt-core
+            adapter: dbt-bigquery
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+      - name: Build image
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: docker/Dockerfile
+          tags: crucible:ci
+          load: true
+          push: false
+      - name: Start emulator and wait for health
+        env:
+          DIALECT: ${{ matrix.dialect }}
+          PORT: ${{ matrix.port }}
+        run: |
+          docker run -d --name crucible -p "127.0.0.1:${PORT}:${PORT}" \
+            crucible:ci serve --dialect "$DIALECT" --port "$PORT"
+          for _ in $(seq 60); do
+            if curl -fsS --max-time 2 "http://127.0.0.1:${PORT}/_crucible/health" >/dev/null; then
+              echo "healthy on port ${PORT}"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "not healthy after 60s" >&2
+          docker logs crucible >&2 || true
+          exit 1
+      - name: Run dbt tests
+        env:
+          CORE_SPEC: ${{ matrix.core }}
+          ADAPTER_SPEC: ${{ matrix.adapter }}
+          DIALECT: ${{ matrix.dialect }}
+          CRUCIBLE_URL: http://127.0.0.1:${{ matrix.port }}
+        run: uv run --with "$CORE_SPEC" --with "$ADAPTER_SPEC" pytest -m dbt tests/dbt -k "$DIALECT"

crucible_emulator-0.1.0a2/.github/workflows/corpus-record.yml

@@ -0,0 +1,100 @@
+name: Corpus record
+
+# Records corpus cases against a real warehouse, which spends credits. Manual runs only.
+on:
+  workflow_dispatch:
+    inputs:
+      dialect:
+        description: Warehouse to record against
+        type: choice
+        options: [bigquery, snowflake]
+        required: true
+      path:
+        description: Directory for the recorded YAML. Empty means corpus/<dialect>
+        type: string
+        default: ""
+      max_bytes_billed:
+        description: BigQuery bytes-billed cap per query (ignored for Snowflake)
+        type: string
+        default: "104857600"
+
+permissions:
+  contents: read
+
+jobs:
+  record:
+    if: github.repository == 'CallumWalterWhite/crucible'
+    runs-on: ubuntu-24.04
+    environment: corpus-record
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write  # Workload Identity Federation
+    env:
+      DIALECT: ${{ inputs.dialect }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - name: Install dependencies for the dialect
+        run: uv sync --locked --extra "record-$DIALECT"
+
+      # Workload Identity Federation: no long-lived key. The provider and service account are
+      # repository variables, not secrets; the service account only needs BigQuery job and
+      # dataset create/delete rights in the sandbox project.
+      - name: Authenticate to Google Cloud
+        if: inputs.dialect == 'bigquery'
+        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0
+        with:
+          workload_identity_provider: ${{ vars.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
+
+      - name: Set the BigQuery project
+        if: inputs.dialect == 'bigquery'
+        env:
+          BIGQUERY_PROJECT: ${{ vars.BIGQUERY_PROJECT }}
+        run: echo "BIGQUERY_PROJECT=$BIGQUERY_PROJECT" >> "$GITHUB_ENV"
+
+      # TODO(phase-5): move Snowflake to key-pair auth; password secrets are a stopgap.
+      - name: Write Snowflake credentials
+        if: inputs.dialect == 'snowflake'
+        env:
+          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
+          SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
+          SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
+          SNOWFLAKE_WAREHOUSE: ${{ secrets.SNOWFLAKE_WAREHOUSE }}
+        run: |
+          set -euo pipefail
+          echo "::add-mask::$SNOWFLAKE_PASSWORD"
+          {
+            echo "SNOWFLAKE_ACCOUNT=$SNOWFLAKE_ACCOUNT"
+            echo "SNOWFLAKE_USER=$SNOWFLAKE_USER"
+            echo "SNOWFLAKE_PASSWORD=$SNOWFLAKE_PASSWORD"
+            echo "SNOWFLAKE_WAREHOUSE=$SNOWFLAKE_WAREHOUSE"
+          } >> "$GITHUB_ENV"
+
+      - name: Record corpus cases
+        env:
+          INPUT_PATH: ${{ inputs.path }}
+          MAX_BYTES: ${{ inputs.max_bytes_billed }}
+        run: |
+          set -euo pipefail
+          path="${INPUT_PATH:-corpus/$DIALECT}"
+          echo "CORPUS_PATH=$path" >> "$GITHUB_ENV"
+          uv run --no-sync crucible corpus record \
+            --dialect "$DIALECT" \
+            --path "$path" \
+            --max-bytes-billed "$MAX_BYTES" \
+            --i-understand-this-spends-credits
+
+      - name: Open pull request with recorded cases
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          branch: corpus-record/${{ inputs.dialect }}
+          base: main
+          add-paths: ${{ env.CORPUS_PATH }}
+          commit-message: "corpus: record ${{ inputs.dialect }} cases"
+          title: "corpus: record ${{ inputs.dialect }} cases"
+          body: |
+            Recorded by workflow run ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}.

crucible_emulator-0.1.0a2/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build everything but publish nothing
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  checks:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    runs-on: ubuntu-24.04
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - name: Read package version
+        id: version
+        run: echo "version=$(uv version --short)" >> "$GITHUB_OUTPUT"
+      - name: Validate release tag
+        if: github.event_name == 'push' || inputs.dry_run == false
+        env:
+          PACKAGE_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          test "$GITHUB_REF_TYPE" = tag
+          test "$GITHUB_REF_NAME" = "v$PACKAGE_VERSION"
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: [build, checks]
+    if: vars.PYPI_PUBLISHING_ENABLED == 'true' && (github.event_name == 'push' || inputs.dry_run == false)
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  image:
+    needs: [build, checks]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+      - name: Log in to GitHub Container Registry
+        if: github.event_name == 'push' || inputs.dry_run == false
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push image
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: docker/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name == 'push' || inputs.dry_run == false }}
+          tags: |
+            ghcr.io/callumwalterwhite/crucible-emulator:v${{ needs.build.outputs.version }}
+            ghcr.io/callumwalterwhite/crucible-emulator:latest
+          labels: |
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.version=${{ needs.build.outputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.licenses=Apache-2.0

crucible_emulator-0.1.0a2/.gitignore

@@ -0,0 +1,13 @@
+.local/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+.claude/scheduled_tasks.lock
+# google-github-actions/auth credential files
+gha-creds-*.json
+.claude/
+.vscode/
+logs/

crucible_emulator-0.1.0a2/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+# Install once with `uv run pre-commit install`. CI runs the same ruff, pyright and import-linter checks.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: lint-imports
+        name: lint-imports
+        entry: uv run lint-imports
+        language: system
+        types: [python]
+        pass_filenames: false

crucible_emulator-0.1.0a2/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+Local BigQuery API emulator on DuckDB (Snowflake planned). Pre-alpha.
+
+## Commands (use `uv run`)
+
+Setup: `uv sync --all-extras` then `uv run pre-commit install`.
+
+Pre-PR checks (same as CI `lint` job, in this order):
+```sh
+uv run ruff check
+uv run ruff format --check
+uv run pyright
+uv run lint-imports
+uv run pytest
+```
+Default `pytest` runs only `tests/unit` + `tests/corpus`. Single test: `uv run pytest <path> [-k name]`. Single corpus case without a server: `uv run crucible corpus run --dialect bigquery --path corpus/bigquery/<area>/<case>.yaml`.
+
+`clients`/`dbt` suites need a running Docker image + `CRUCIBLE_URL` (see `.github/workflows/ci.yml`); don't run them locally by default. `serve` needs the `server` extra (`--all-extras` covers it).
+
+## Architecture
+
+Layers enforced by `import-linter` (`pyproject.toml`): `crucible.cli` → `crucible.server | crucible.corpus` → `crucible.dialects` → `crucible.engine`. `bigquery` and `snowflake` dialect packages never import each other; engine is warehouse-agnostic and sees dialects only via the `Dialect` protocol (type-checking only). Request flow: `server/<dialect>` → `engine.Pipeline` (`dialect.split` → `dialect.plan` → `SqlPlan | CommandPlan`) → `Result` → dialect types → wire response.
+
+- `engine/`: `engine.py` (one DuckDB, UTC-pinned, cursor per request), `catalog.py` (quote all identifiers via `engine.catalog.quote()`), `session.py`, `pipeline.py`, `types.py`, `errors.py`.
+- `dialects/<d>/`: `statements.py`, `translate.py` (schema-aware: qualify against live catalog, annotate, transform, generate with the dialect's own SQLGlot DuckDB-generator subclass), `ddl.py`, `dml.py`, `types.py`, `metadata.py`, `errors.py`, `dialect.py`.
+- `dialects/<d>/transforms/`: one module per area; ordered list `PIPELINE` in `transforms/__init__.py` is the only ordering. Transforms run on the qualified type-annotated AST, must preserve `.type` on rebuilt nodes, and raise `CrucibleUnsupportedError` for anything inexact.
+- `server/`: one Starlette app per dialect per process. BigQuery `:9050`, Snowflake `:8080`, bind `127.0.0.1` by default (`CRUCIBLE_HOST=0.0.0.0` only inside Docker). Health: `GET /_crucible/health`. Unknown endpoints return the warehouse's "not implemented" shape, never a generic 404. Never expose on a network — no auth by design.
+
+## Rules that fail CI or waste money
+
+- **Unsupported means explicit.** Never return a best guess; raise `CrucibleUnsupportedError` (mapped to the warehouse error at the server edge). `docs/architecture.md` + ADRs are design truth; `CONTRIBUTING.md` has the workflow.
+- **Corpus is the proof.** Cases live in `corpus/<dialect>/<area>/<case>.yaml`. Never hand-set `verified: true` or `recorded_at` — only `crucible corpus record` writes them, and CI (`scripts/check-corpus-verified.sh`) fails any PR outside `corpus-record/*` that adds `verified: true`. Contributors never run `record`/`record-api` (spends real warehouse credits, requires `--max-bytes-billed` + `--i-understand-this-spends-credits`, maintainers only).
+- **Every response shape needs a one-line comment** citing the client source or official API doc. Upstream SQLGlot bugs go upstream; keep only a local workaround with a comment linking the upstream PR.
+- **Exact pins** `sqlglot==30.22.0`, `duckdb==1.5.6` are deliberate (ADR 0008) — do not loosen. `pytz` is a core dep (DuckDB needs it for TZ values). Python 3.11–3.13; `pyright` is `strict` on `src` only; ruff line-length 100.
+- **`docs/compatibility.md` is generated** from corpus/client results — never hand-edit. Wire fixtures in `tests/fixtures/bigquery_api/` are redacted in code before writing.

crucible_emulator-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project does not yet follow semantic versioning.
+
+## [Unreleased]
+
+## [0.1.0a2] - 2026-10-20
+
+### Added
+
+- Multipart uploads (`uploadType=multipart`) for CSV load jobs, used by dbt Fusion for seeds.
+- CSV loads accept the BOOL spellings `True` and `False`, as written by Python tools.
+- `examples/dbt-bigquery`: an original dbt project with seeds, views, tables, data tests and unit tests.
+- README sections on supported dbt versions, current limits and alternatives.
+- Issue templates for bug reports and unsupported features.
+
+### Changed
+
+- The Python client examples moved to `examples/python-bigquery`.
+- The project is described as a BigQuery emulator, with Snowflake planned.
+
+### Fixed
+
+- `crucible corpus record-api` now removes stale fixtures with three-digit numbers.
+- Time travel (`FOR SYSTEM_TIME AS OF`) and functions DuckDB lacks (such as `ST_*`) raise
+  `Not supported by Crucible` instead of a DuckDB parser or catalog error.
+
+## [0.1.0a1] - 2026-10-17
+
+### Added
+
+- Initial project scaffolding.
+- BigQuery translation backbone: schema-aware translation, output types from the BigQuery AST,
+  BigQuery literal typing, NUMERIC as DECIMAL(38,9), CREATE TABLE and INSERT with BigQuery coercion.
+- BigQuery error parity, SAFE., function fixes, UNNEST, ARRAY_AGG and the statements dbt emits.
+- `crucible corpus record-api`: redacted wire-format fixtures from the real BigQuery REST API.