constructive-io · pyramation · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -55,6 +55,26 @@ packages/
 * **One change per file** in each folder. If your deploy spans multiple SQL statements, they all live in that one file — see *revert mechanics* below.
 
 
+## Generated artifacts (`sql/`)
+
+`pgpm package` writes two committed artifacts per module, both derived from
+`deploy/` + `pgpm.plan` and both **never hand-edited**:
+
+```bash
+pgpm package    # sql/<name>--<version>.sql  and  sql/<name>--<version>.bundle.tar.gz
+pgpm deploy --fast   # deploy from the bundle: verify sha256, one-shot execute, write the ledger
+```
+
+The `.bundle.tar.gz` is a gzipped tarball of the module's JSON migration bundle
+(plan + per-change SQL + sha256 digest); output is byte-reproducible, so
+re-running `pgpm package` on unchanged sources produces no diff. `--fast` falls
+back to building from `deploy/` when the artifact is missing or stale, so a
+forgotten regeneration is a slowdown, not a failure — but regenerate both files
+in the same commit as any `deploy/` change.
+
+Requires the pgpm 5 CLI (`PGPM_VERSION` in the workflows); the pgpm 4 CLI
+neither emits bundles nor honours `extensions.json`'s `schema`/`createSchema`.
+
 ## Physical mechanics
 
 ### Deploy

diff --git a/packages/achievements/sql/pgpm-achievements--0.33.0.bundle.tar.gz b/packages/achievements/sql/pgpm-achievements--0.33.0.bundle.tar.gz
diff --git a/packages/app-scope/sql/pgpm-app-scope--0.33.1.bundle.tar.gz b/packages/app-scope/sql/pgpm-app-scope--0.33.1.bundle.tar.gz
diff --git a/packages/base32/sql/pgpm-base32--0.33.0.bundle.tar.gz b/packages/base32/sql/pgpm-base32--0.33.0.bundle.tar.gz
diff --git a/packages/database-jobs/sql/pgpm-database-jobs--0.33.1.bundle.tar.gz b/packages/database-jobs/sql/pgpm-database-jobs--0.33.1.bundle.tar.gz
diff --git a/packages/defaults/sql/pgpm-defaults--0.33.0.bundle.tar.gz b/packages/defaults/sql/pgpm-defaults--0.33.0.bundle.tar.gz
diff --git a/packages/encrypted-secrets-table/sql/pgpm-encrypted-secrets-table--0.33.0.bundle.tar.gz b/packages/encrypted-secrets-table/sql/pgpm-encrypted-secrets-table--0.33.0.bundle.tar.gz
diff --git a/packages/encrypted-secrets/sql/pgpm-encrypted-secrets--0.33.0.bundle.tar.gz b/packages/encrypted-secrets/sql/pgpm-encrypted-secrets--0.33.0.bundle.tar.gz
diff --git a/packages/faker/sql/pgpm-faker--0.33.0.bundle.tar.gz b/packages/faker/sql/pgpm-faker--0.33.0.bundle.tar.gz
diff --git a/packages/function-resolution/sql/pgpm-function-resolution--0.33.1.bundle.tar.gz b/packages/function-resolution/sql/pgpm-function-resolution--0.33.1.bundle.tar.gz
diff --git a/packages/geotypes/sql/pgpm-geo-types--0.33.0.bundle.tar.gz b/packages/geotypes/sql/pgpm-geo-types--0.33.0.bundle.tar.gz
diff --git a/packages/inflection-db/sql/inflection-db--0.33.0.bundle.tar.gz b/packages/inflection-db/sql/inflection-db--0.33.0.bundle.tar.gz
diff --git a/packages/inflection/sql/pgpm-inflection--0.33.0.bundle.tar.gz b/packages/inflection/sql/pgpm-inflection--0.33.0.bundle.tar.gz
diff --git a/packages/jobs/sql/pgpm-jobs--0.33.0.bundle.tar.gz b/packages/jobs/sql/pgpm-jobs--0.33.0.bundle.tar.gz
diff --git a/packages/jwt-claims/sql/pgpm-jwt-claims--0.33.0.bundle.tar.gz b/packages/jwt-claims/sql/pgpm-jwt-claims--0.33.0.bundle.tar.gz
diff --git a/packages/ltree-helpers/sql/pgpm-ltree-helpers--0.33.0.bundle.tar.gz b/packages/ltree-helpers/sql/pgpm-ltree-helpers--0.33.0.bundle.tar.gz
diff --git a/packages/measurements/sql/pgpm-measurements--0.33.0.bundle.tar.gz b/packages/measurements/sql/pgpm-measurements--0.33.0.bundle.tar.gz
diff --git a/packages/metaschema-modules/sql/metaschema-modules--0.33.1.bundle.tar.gz b/packages/metaschema-modules/sql/metaschema-modules--0.33.1.bundle.tar.gz
diff --git a/packages/metaschema-schema/sql/metaschema-schema--0.33.1.bundle.tar.gz b/packages/metaschema-schema/sql/metaschema-schema--0.33.1.bundle.tar.gz
diff --git a/packages/object-store/sql/object-store--0.33.1.bundle.tar.gz b/packages/object-store/sql/object-store--0.33.1.bundle.tar.gz
diff --git a/packages/object-tree/sql/object-tree--0.33.1.bundle.tar.gz b/packages/object-tree/sql/object-tree--0.33.1.bundle.tar.gz
diff --git a/packages/partman/sql/pgpm-partman--0.33.0.bundle.tar.gz b/packages/partman/sql/pgpm-partman--0.33.0.bundle.tar.gz
diff --git a/packages/stamps/sql/pgpm-stamps--0.33.0.bundle.tar.gz b/packages/stamps/sql/pgpm-stamps--0.33.0.bundle.tar.gz
diff --git a/packages/totp/sql/pgpm-totp--0.33.0.bundle.tar.gz b/packages/totp/sql/pgpm-totp--0.33.0.bundle.tar.gz
diff --git a/packages/types/sql/pgpm-types--0.33.0.bundle.tar.gz b/packages/types/sql/pgpm-types--0.33.0.bundle.tar.gz
diff --git a/packages/utils/sql/pgpm-utils--0.33.0.bundle.tar.gz b/packages/utils/sql/pgpm-utils--0.33.0.bundle.tar.gz
diff --git a/packages/uuid/sql/pgpm-uuid--0.33.0.bundle.tar.gz b/packages/uuid/sql/pgpm-uuid--0.33.0.bundle.tar.gz
diff --git a/packages/verify/sql/pgpm-verify--0.33.0.bundle.tar.gz b/packages/verify/sql/pgpm-verify--0.33.0.bundle.tar.gz