Stumble · Stumble · Sep 9, 2026 · Sep 9, 2026
diff --git a/GUIDE.md b/GUIDE.md
@@ -16,11 +16,13 @@ NOTE: this combo is for PostgreSQL, if you are using MySQL, you can checkout thi
 [Needle](https://github.com/Stumble/needle). It provides the same set of functionalities
 as this combo.
 
-Production versions:
+wicked-sqlc has its own [release tags](https://github.com/Stumble/sqlc/releases),
+independent of upstream sqlc's version numbers. We regularly rebase our changes
+onto upstream releases.
 
-+ sqlc: v2.3.4-wicked-fork
-+ dcache: v0.3.0 (Note: redis/v8 users please use v0.1.4)
-+ wgpx: v0.3.1
+The generator update does not require upgrading your application's wpgx or
+dcache dependencies. See the [bookstore go.mod](https://github.com/Stumble/bookstore/blob/main/go.mod)
+for a tested runtime dependency set.
 
 # Sqlc (this wicked fork)
 
@@ -50,42 +52,45 @@ your customers are disappointed, or (2) before the product is launched, writing
 
 ## Install
 
+Build this fork from source using the Go version required by [go.mod](go.mod).
+The default build uses CGO and requires a C compiler. Ensure Go's installation
+directory (`GOBIN`, or `GOPATH/bin` when unset) is on your `PATH`.
+
 ```bash
-# cgo must be enabled because: https://github.com/pganalyze/pg_query_go
 git clone https://github.com/Stumble/sqlc.git
-cd sqlc/
-git checkout v2.3.4
+cd sqlc
 make install
 sqlc version
-# you shall see: v2.3.4-wicked-fork
 ```
 
-### Upstream synchronization development
+This installs the current `main` branch. For a reproducible build, check out a
+published tag from [Releases](https://github.com/Stumble/sqlc/releases) before
+running `make install`. A build from tag `vX.Y.Z` reports `vX.Y.Z-wicked-fork`;
+untagged builds include a Git-derived version identifier.
 
-The migration branch applies two commits directly on upstream **v1.31.1**:
-core compiler/protocol changes, followed by the wicked backend and its integration.
-It uses Go 1.26.8 (the Go
-toolchain can select this automatically) and keeps the same `make install`,
-`sqlc generate`, `sqlc diff`, and `sql_package: wpgx` entrypoints. It is a single
-executable; no additional codegen plugin needs to be installed.
+CGO is optional. To install without a C compiler:
 
 ```bash
-git checkout refactor/wicked-on-upstream
-make install
-# The upstream parser also supports builds without CGO:
-make build CGO_ENABLED=0
+make install CGO_ENABLED=0
 ```
 
+Use `make build` to create `bin/sqlc` without installing it. `sqlc generate`,
+`sqlc diff`, and `sql_package: wpgx` remain the entrypoints for existing projects.
+There is one executable and no separate codegen plugin to install.
+
+### Architecture and development
+
 The compiler handles schema dependencies, the primary model, and SQL types.
 `internal/codegen/wicked` owns the Go mapping, templates, comment options, cache
 keys, timeouts, invalidation, and replica APIs. Standard Go generation remains
 in the upstream backend. Wicked facts are transported in `WickedMetadata`;
 `-- -- key: value` options use the standard query comments.
 
-For reproducible migration fixtures, CI builds with
+For reproducible compatibility fixtures, CI builds with
 `make build COMMIT_HASH=v2.4.0-dev`. This development label is not a published
-release. General compiler fixes are committed in this fork first and are only
-proposed upstream after the complete fork and downstream tests pass.
+release and does not identify the version installed from a release tag. General
+compiler fixes are committed in this fork first and are only proposed upstream
+after the complete fork and downstream tests pass.
 
 Compatibility is checked against v2.3.4, including the full `github.com/google/uuid`
 type identity, inherited primary models, generated Row types, and JSON/cache
@@ -379,9 +384,9 @@ LIMIT @first;
 
 This wicked forked sqlc adds 3 abilities to query: cache, timeout and invalidate.
 
-All of them are added by extending sqlc to allow passing additional options per each query.
-Originally, you can only specify name and the type of result in the comments before SQL.
-The new feature allows you to pass any options to codegen backend by adding comments starts with `-- --`.
+Options are written as `-- -- key: value` comments above each query. sqlc passes
+them through its standard query comments, and the wicked backend parses and
+validates them. They do not require a separate custom-parameter protocol.
 
 For example, this will generate code that caches the result of all books for 10 minutes, with 500 milliseconds timeout.
 

diff --git a/docs/changelogs/2026-09-09-prepare-wicked-v2.4.0.md b/docs/changelogs/2026-09-09-prepare-wicked-v2.4.0.md
@@ -0,0 +1,118 @@
+# Refresh the guide and prepare wicked-sqlc v2.4.0
+
+## 1. Current State
+
+The migration and README PRs are merged on `main` at
+`fff88434a16a113e915e15ef85c3136d96c8e78c`; its Go and wicked workflows passed.
+The latest published release is v2.3.4. The guide still points to that old tag and
+the migration branch, and says CGO is mandatory.
+
+Prior releases have no binary attachments. The current workflows do not publish
+on tag or release events; `scripts/release.go` has disabled Equinox publishing.
+No new distribution infrastructure is needed for a source release.
+
+## 2. Intended Behavior
+
+- B1: Document current-main builds and reproducible release-tag builds without
+  tying the architecture to one upstream release or a migration branch.
+- B2: Explain optional CGO, version output, runtime dependencies, and the existing
+  comment-based backend options accurately.
+- B3: Prepare v2.4.0 notes with upgrade instructions and honest validation scope.
+- F1: Do not publish an unmerged preparation branch or imply an unpublished tag
+  exists. Do not reset checkouts, switch downstream binaries, or deploy services.
+
+## 3. Decisions and Risks
+
+- D1: Change only GUIDE.md, release notes, and this record; preserve the README
+  and its original upstream section.
+- D2: Use v2.4.0 as the next minor release, following the existing wicked version
+  series and the migration's v2.4.0-dev test label. Do not move old tags.
+- D3: Keep the existing tag + GitHub Release/source distribution model. No new
+  release workflow, registry publishing, or binary-attachment contract.
+- D4: Submit the preparation PR and wait for human merge before creating the
+  release tag on the exact verified `main` commit. Publication is a separate
+  post-merge step, not automatic PR merging.
+- R1: A release label must match the CLI and generated headers in both build modes.
+- R2: Existing generated snapshots use a development label; compare them with
+  release-candidate output while ignoring only the version-comment line.
+
+## 4. Scope and Checklist
+
+- [x] Inspect merged code, guide, current releases, and all publishing triggers.
+- [x] Refresh the install/architecture/options sections and prepare release notes.
+- [x] Verify CGO/non-CGO installs into isolated directories and version output.
+- [x] Run release-version regression tests and bookstore generation parity.
+- [x] Review the complete diff and prepare the PR handoff.
+
+Secret scanning, publication, and current-head CI/review monitoring follow the
+normal push workflow; their live results are recorded on the PR.
+
+## 5. Verification Plan
+
+E2E Required: no for this docs-only preparation PR. The product tree is unchanged
+from the already tested migration; PR CI will rerun the existing runtime suites.
+
+- `git diff --check` and a non-documentation diff against `origin/main`.
+- Build with `make install COMMIT_HASH=v2.4.0` and its `CGO_ENABLED=0` variant,
+  setting `GOBIN` to separate temporary directories so the user's binary is not
+  replaced. Check both binaries report `v2.4.0-wicked-fork`.
+- `GOMAXPROCS=2 go test -p 2 -count=1 ./scripts ./internal/cmd -run 'Test(ReleaseVersionMatchesGeneratedCode|Wicked)'`.
+- Clone bookstore `main` in a temporary directory; generate with each candidate
+  binary, compare tracked Go output ignoring only SQLC version comments, and run
+  `sqlc diff`. Check generated headers report the release-candidate version.
+- Check new documentation links and installation snippets against the Makefile.
+- No `make lint-fix` target exists in sqlc; lint is unavailable, without a
+  substitute command. No full local Alva service-stack tests are claimed.
+
+## 6. Human Decisions
+
+The user approved updating GUIDE and preparing a formal release. The announced
+target is v2.4.0. The human still merges the preparation PR; there is no approval
+to bypass the PR workflow or modify downstream deployments.
+
+## 7. Outcome and Evidence
+
+The guide now matches the merged architecture and installation model. Release
+notes are ready in `docs/releases/v2.4.0.md`; no v2.4.0 tag or release has been
+created. Changes remain limited to three Markdown files.
+
+| Item | Evidence | Status |
+| --- | --- | --- |
+| B1, B2 | Guide removes old tag/branch directions and documents both build modes | DONE |
+| B3 | Upgrade notes include compatibility evidence and known limits | DONE |
+| D1, F1 | README/product unchanged; only temporary installations/clones used | DONE |
+| D2, D3 | v2.4.0 unused; existing source-release convention inspected | DONE |
+| D4 | Human merge and exact-main publication remain explicit prerequisites | DONE |
+| R1 | Both CLI builds and generated headers report v2.4.0-wicked-fork | DONE |
+| R2 | Both generators match all 17 bookstore Go files except version comments | DONE |
+
+Fresh checks from `/home/forge/worktrees/sqlc-wicked-release`:
+
+- `GOMAXPROCS=2 GOBIN=/tmp/sqlc-v2.4-release.jAOb4e/cgo make install COMMIT_HASH=v2.4.0`
+  and `GOMAXPROCS=2 GOBIN=/tmp/sqlc-v2.4-release.jAOb4e/nocgo make install CGO_ENABLED=0 COMMIT_HASH=v2.4.0`
+  both passed. Each isolated binary's `version` command reports the expected
+  `v2.4.0-wicked-fork`; no installed user binary was replaced.
+- `GOMAXPROCS=2 go test -p 2 -count=1 ./scripts ./internal/cmd -run 'Test(ReleaseVersionMatchesGeneratedCode|Wicked)'`
+  passed: scripts 8.680s, cmd 0.109s, including an actual release-binary/header test.
+- `node /tmp/sqlc-v2.4-release.jAOb4e/verify.mjs` passed: both binaries generate and
+  pass `sqlc diff`, all 17 outputs match bookstore after removing only the version
+  comment, every generated header has the candidate version, and no untracked
+  generated files appear. Documentation links/fences and unchanged README pass.
+- The isolated bookstore clone is merged `main` at
+  `444685d1b6fe870143f9e8aef190410e9a30570b`. From that clone,
+  `GOMAXPROCS=2 go test -p 2 -count=1 ./pkg/repos/...` passed compilation of all
+  five generated packages; these packages contain no test files.
+- `git diff --check` passed. The complete diff was reviewed against `origin/main`
+  for scope, architecture, compatibility, test claims, operations, and prose.
+  No unresolved findings. No product, workflow, dependency, or migration changes.
+
+The new tag-clone example cannot run before publication; it is prepared release
+text, not evidence that the tag already exists. Post-merge verification remains
+required below. No full local runtime or Alva service-stack rerun is claimed.
+
+## 8. Remaining Work
+
+Human merge of the preparation PR, then verify current `main`, ensure v2.4.0 is
+still unused, create the tag and source release using `docs/releases/v2.4.0.md`,
+and verify the published tag, notes, and fresh tag-clone installation. Do not
+claim the formal release is complete before those post-merge checks pass.
diff --git a/docs/releases/v2.4.0.md b/docs/releases/v2.4.0.md
@@ -0,0 +1,59 @@
+# wicked-sqlc v2.4.0
+
+This release brings the wicked fork onto a modern upstream sqlc base and separates
+its compiler changes from a dedicated Go backend. The CLI and existing wpgx
+configuration stay the same; no additional plugin is required.
+
+## Highlights
+
+- A dedicated `internal/codegen/wicked` backend owns Go type mappings, templates,
+  timeout/cache options, invalidation hooks, replica APIs, and test helpers.
+- The compiler retains wicked schema ownership and dependency conventions, with
+  focused metadata passed to the backend. Query options use ordinary comments.
+- Parameter inference handles repeated unaliased table references across CTEs
+  without introducing false ambiguity; distinct self-join aliases remain distinct.
+- Compatibility coverage includes Google UUID types, inherited primary models,
+  generated Row types, nullable parameters, and JSON/cache payloads.
+- Both CGO and non-CGO builds are supported. Building the generator requires
+  Go 1.26.8; existing application runtime dependencies do not need to change.
+
+## Upgrade
+
+Install from the release tag:
+
+```sh
+git clone --branch v2.4.0 --depth 1 https://github.com/Stumble/sqlc.git
+cd sqlc
+make install
+sqlc version
+# v2.4.0-wicked-fork
+```
+
+Use `make install CGO_ENABLED=0` if a C compiler is unavailable. Ensure Go's
+installation directory is on `PATH`. This is a source release, following the
+existing distribution model; there are no prebuilt binary attachments.
+
+Keep `sql_package: wpgx`, your existing SQL/configuration, and compatible wpgx and
+dcache versions. Regenerate with `sqlc generate`, review the diff, and run your
+application tests. Version comments change when moving from an older binary.
+
+The same-input compatibility audit against v2.3.4 covered 8 downstream
+repositories, 226 configurations, and 689 regenerated Go files; those files
+differed only in version comments. Full Go builds passed in 7 repositories.
+Trex's generated packages compiled, but its full local build exceeded the test
+environment's memory limit. This was not a full Alva service-stack E2E run.
+
+The sqlc test suite and bookstore generation/runtime tests passed on the
+migrated implementation. See the
+[migration record](https://github.com/Stumble/sqlc/blob/main/docs/changelogs/2026-09-08-sync-upstream-and-separate-wicked-codegen.md)
+for the scope and limitations of that validation.
+
+## Existing limits
+
+Top-level SELECT classification is not a proof that a query is read-only.
+Ordinary views cannot be the primary wicked model. Wicked batch commands,
+`:execlastid`, and database-only analysis are unsupported; `:copyfrom` does not
+implement cache or invalidation options.
+
+See the [guide](https://github.com/Stumble/sqlc/blob/main/GUIDE.md) and
+[bookstore example](https://github.com/Stumble/bookstore) for setup and usage.