feat(v18): overridable wasm memory flags + pg18-lowmem-* publish flow

PUBLISH.md

@@ -174,6 +174,56 @@ npm install libpg-query@pg18   # full API
 npm install libpg-query@pg17   # parse only
 ```
 
+## Low-Memory Variants (pg18-lowmem-*)
+
+Special opt-in builds with a smaller WebAssembly memory floor, published under
+dedicated dist-tags so they can never affect `latest` or `pg18`. The Makefiles
+accept overrides (defaults unchanged: 128MiB initial / 1GiB max / 32MiB stack):
+
+| Tag              | WASM_INITIAL_MEMORY | WASM_STACK_SIZE |
+|------------------|---------------------|-----------------|
+| `pg18-lowmem-16` | 16777216 (16MiB)    | 4194304 (4MiB)  |
+| `pg18-lowmem-32` | 33554432 (32MiB)    | 8388608 (8MiB)  |
+| `pg18-lowmem-64` | 67108864 (64MiB)    | 33554432 (32MiB, default) |
+
+Note: `INITIAL_MEMORY` must exceed `STACK_SIZE` + static data (~2.5MiB), which
+is why the smaller floors also lower the stack. A smaller stack only limits
+extremely deep expression nesting (depth 5000 still parses on the 4MiB stack).
+
+### Exact publish steps (per variant)
+
+```bash
+# 1. Start clean — the working tree must have no uncommitted changes
+git status
+
+cd versions/18
+
+# 2. Set a prerelease version so it can never shadow a normal release.
+#    Pattern: <current-version>-lowmem-<floor>.<n>   e.g. 18.1.5-lowmem-32.0
+npm version 18.1.5-lowmem-32.0 --no-git-tag-version
+
+# 3. Build the wasm with the memory overrides (32MiB floor shown)
+pnpm wasm:clean
+pnpm wasm:make build WASM_INITIAL_MEMORY=33554432 WASM_STACK_SIZE=8388608
+pnpm build:js
+
+# 4. Test against the variant build
+pnpm test
+
+# 5. Publish under the variant tag (TAG overrides x-publish.distTag)
+TAG=pg18-lowmem-32 pnpm run publish:pkg
+
+# 6. IMPORTANT: revert the version bump and rebuild the default wasm so the
+#    working tree is back to the normal publish state
+git checkout -- package.json
+pnpm build
+
+# 7. Verify the tags: latest/pg18 must be untouched
+npm dist-tag ls libpg-query
+```
+
+Consumers install with e.g. `npm install libpg-query@pg18-lowmem-32`.
+
 ## Parser Package (@pgsql/parser)
 
 ### Quick Publish

versions/18/Makefile

@@ -6,6 +6,12 @@
 WASM_OUT_DIR := wasm
 WASM_OUT_NAME := libpg-query
 WASM_MODULE_NAME := PgQueryModule
+
+# WASM memory configuration (bytes). Override on the make command line for
+# low-memory variants, e.g. `make build WASM_INITIAL_MEMORY=33554432` (32MiB).
+WASM_INITIAL_MEMORY ?= 134217728
+WASM_MAXIMUM_MEMORY ?= 1073741824
+WASM_STACK_SIZE ?= 33554432
 # LIBPG_QUERY_REPO := https://github.com/pganalyze/libpg_query.git
 # LIBPG_QUERY_TAG := 18.0.0
 LIBPG_QUERY_REPO := https://github.com/constructive-io/libpg_query.git
@@ -73,9 +79,9 @@ ifdef EMSCRIPTEN
 		-sMODULARIZE=1 \
 		-sEXPORT_ES6=0 \
 		-sALLOW_MEMORY_GROWTH=1 \
-		-sINITIAL_MEMORY=134217728 \
-		-sMAXIMUM_MEMORY=1073741824 \
-        -sSTACK_SIZE=33554432 \
+		-sINITIAL_MEMORY=$(WASM_INITIAL_MEMORY) \
+		-sMAXIMUM_MEMORY=$(WASM_MAXIMUM_MEMORY) \
+        -sSTACK_SIZE=$(WASM_STACK_SIZE) \
 		-lpg_query \
 		-o $@ \
 		$(SRC_FILES)