spoc-504: 5.x -> 6.x upgrade path and version safety nets

Makefile

@@ -16,6 +16,7 @@ vpath % src src/compat/$(PGVER)
 DATA = $(wildcard sql/$(EXTENSION)*--*.sql)
 SRCS := $(wildcard src/*.c) \
         $(wildcard src/compat/$(PGVER)/*.c)
+
 OBJS = $(filter-out src/spock_output.o, $(SRCS:.c=.o))
 
 PG_CPPFLAGS += -I$(libpq_srcdir) \
@@ -64,7 +65,7 @@ REGRESS = preseed infofuncs init_fail init preseed_check basic conflict_secondar
 		  row_filter_sampling att_list column_filter apply_delay alter_options \
 		  extended node_origin_cascade multiple_upstreams tuple_origin autoddl \
 		  sync_event sync_table generated_columns spill_transaction read_only \
-		  resolutions_retention drop
+		  resolutions_retention version_guard drop
 
 # The following test cases are disabled while developing.
 #

docs/conflicts.md

@@ -33,24 +33,47 @@ conflicts with the following logic:
 Note that on a conflicting transaction, the delta-apply column will be
 correctly calculated and applied.
 
-To make a column a conflict-free delta-apply column, ensuring that the value
-replicated is the delta of the committed changes (the old value plus or
-minus any new value) to a given record, you need to apply the following
-settings to the column: `log_old_value=true,
-delta_apply_function=spock.delta_apply`. For example:
+To make a column a conflict-free delta-apply column, ensuring that the
+value replicated is the delta of the committed changes (the old value
+plus or minus any new value) to a given record, attach a SECURITY LABEL
+to the column via the `spock.delta_apply()` helper:
 
 ```sql
-ALTER TABLE pgbench_accounts ALTER COLUMN abalance
-  SET (log_old_value=true, delta_apply_function=spock.delta_apply);
-ALTER TABLE pgbench_branches ALTER COLUMN bbalance
-  SET (log_old_value=true, delta_apply_function=spock.delta_apply);
-ALTER TABLE pgbench_tellers ALTER COLUMN tbalance
-  SET (log_old_value=true, delta_apply_function=spock.delta_apply);
+SELECT spock.delta_apply('pgbench_accounts'::regclass, 'abalance');
+SELECT spock.delta_apply('pgbench_branches'::regclass, 'bbalance');
+SELECT spock.delta_apply('pgbench_tellers'::regclass,  'tbalance');
 ```
 
-As a special safety-valve feature, if you ever need to re-set a
-`log_old_value` column you can temporarily alter the column to
-`log_old_value` is `false`.
+To remove the marker, pass `to_drop => true`:
+
+```sql
+SELECT spock.delta_apply('pgbench_accounts'::regclass, 'abalance', to_drop => true);
+```
+
+Under the hood, `spock.delta_apply()` writes a row into `pg_seclabel`
+with `provider = 'spock'` and `label = 'spock.delta_apply'`.  The
+binary-upgrade compatibility shim that translates legacy spock 5.x
+reloptions during `pg_upgrade` writes the same canonical label, so
+operators can audit the catalog uniformly:
+
+```sql
+SELECT * FROM pg_seclabel
+ WHERE provider = 'spock' AND label = 'spock.delta_apply';
+```
+
+### Upgrading from spock 5.x
+
+Spock 5.x recorded the same intent as a pair of per-attribute reloptions
+(`log_old_value=true, delta_apply_function=spock.delta_apply`). During
+`pg_upgrade`, the binary-upgrade compatibility shim translates those
+reloptions into the new `SECURITY LABEL` form automatically. Look for
+`NOTICE: spock: rewrote ALTER TABLE … ALTER COLUMN … legacy options to
+SECURITY LABEL` lines in `pg_upgrade.log` to audit the translation.
+After the upgrade, `SELECT * FROM pg_seclabel WHERE provider = 'spock'
+AND label = 'spock.delta_apply'` is the authoritative list of delta-apply
+columns. See
+[Binary-upgrade compatibility shims](internals-doc/binary-upgrade-compat-shim.md)
+for the full design.
 
 ### Conflict Configuration Options
 

docs/troubleshooting.md

@@ -165,8 +165,7 @@ ALTER TABLE table_name ALTER COLUMN column_name SET NOT NULL;
 Then configure the Delta-Apply column with the following command:
 
 ```sql
-ALTER TABLE table_name ALTER COLUMN column_name
-  SET (log_old_value=true, delta_apply_function=spock.delta_apply);
+SELECT spock.delta_apply('table_name'::regclass, 'column_name');
 ```
 
 ## Configuration Issues

include/spock.h

@@ -133,4 +133,7 @@ VALGRIND_PRINTF(const char *format,...)
 
 extern void spock_init_failover_slot(void);
 
+/* lives in src/spock_bucompat_5x.c -- used only under IsBinaryUpgrade */
+extern void register_spock_compat_5x(void);
+
 #endif							/* SPOCK_H */

patches/15/pg15-000-spock-patchset-version.diff

@@ -0,0 +1,32 @@
+Spock core-patchset: export patchset version via miscadmin.h and globals.c.
+
+Adds SPOCK_CORE_PATCHSET_VERSION (compile-time constant) and
+SpockCorePatchsetVersion (runtime global) to the standard places
+PostgreSQL already uses for server-wide state.  No new files.
+
+--- a/src/include/miscadmin.h
++++ b/src/include/miscadmin.h
+@@ -498,4 +498,11 @@
+ /* in executor/nodeHash.c */
+ extern size_t get_hash_memory_limit(void);
+
++/*
++ * Spock core-patchset identity.  Bump the version when the patchset
++ * changes in a way visible to the extension binary.
++ */
++#define SPOCK_CORE_PATCHSET_VERSION 1
++extern PGDLLIMPORT int SpockCorePatchsetVersion;
++
+ #endif							/* MISCADMIN_H */
+--- a/src/backend/utils/init/globals.c
++++ b/src/backend/utils/init/globals.c
+@@ -114,6 +114,9 @@
+ bool		IsBinaryUpgrade = false;
+ bool		IsBackgroundWorker = false;
+
++/* Spock core-patchset identity. */
++int			SpockCorePatchsetVersion = SPOCK_CORE_PATCHSET_VERSION;
++
+ bool		ExitOnAnyError = false;
+
+ int			DateStyle = USE_ISO_DATES;

patches/16/pg16-000-spock-patchset-version.diff

@@ -0,0 +1,32 @@
+Spock core-patchset: export patchset version via miscadmin.h and globals.c.
+
+Adds SPOCK_CORE_PATCHSET_VERSION (compile-time constant) and
+SpockCorePatchsetVersion (runtime global) to the standard places
+PostgreSQL already uses for server-wide state.  No new files.
+
+--- a/src/include/miscadmin.h
++++ b/src/include/miscadmin.h
+@@ -510,4 +510,11 @@
+ /* in executor/nodeHash.c */
+ extern size_t get_hash_memory_limit(void);
+
++/*
++ * Spock core-patchset identity.  Bump the version when the patchset
++ * changes in a way visible to the extension binary.
++ */
++#define SPOCK_CORE_PATCHSET_VERSION 1
++extern PGDLLIMPORT int SpockCorePatchsetVersion;
++
+ #endif							/* MISCADMIN_H */
+--- a/src/backend/utils/init/globals.c
++++ b/src/backend/utils/init/globals.c
+@@ -114,6 +114,9 @@
+ bool		IsBinaryUpgrade = false;
+ bool		IsBackgroundWorker = false;
+
++/* Spock core-patchset identity. */
++int			SpockCorePatchsetVersion = SPOCK_CORE_PATCHSET_VERSION;
++
+ bool		ExitOnAnyError = false;
+
+ int			DateStyle = USE_ISO_DATES;

patches/17/pg17-000-spock-patchset-version.diff

@@ -0,0 +1,32 @@
+Spock core-patchset: export patchset version via miscadmin.h and globals.c.
+
+Adds SPOCK_CORE_PATCHSET_VERSION (compile-time constant) and
+SpockCorePatchsetVersion (runtime global) to the standard places
+PostgreSQL already uses for server-wide state.  No new files.
+
+--- a/src/include/miscadmin.h
++++ b/src/include/miscadmin.h
+@@ -525,4 +525,11 @@
+ /* in executor/nodeHash.c */
+ extern size_t get_hash_memory_limit(void);
+
++/*
++ * Spock core-patchset identity.  Bump the version when the patchset
++ * changes in a way visible to the extension binary.
++ */
++#define SPOCK_CORE_PATCHSET_VERSION 1
++extern PGDLLIMPORT int SpockCorePatchsetVersion;
++
+ #endif							/* MISCADMIN_H */
+--- a/src/backend/utils/init/globals.c
++++ b/src/backend/utils/init/globals.c
+@@ -117,6 +117,9 @@
+ bool		IsUnderPostmaster = false;
+ bool		IsBinaryUpgrade = false;
+
++/* Spock core-patchset identity. */
++int			SpockCorePatchsetVersion = SPOCK_CORE_PATCHSET_VERSION;
++
+ bool		ExitOnAnyError = false;
+
+ int			DateStyle = USE_ISO_DATES;

patches/18/pg18-000-spock-patchset-version.diff

@@ -0,0 +1,32 @@
+Spock core-patchset: export patchset version via miscadmin.h and globals.c.
+
+Adds SPOCK_CORE_PATCHSET_VERSION (compile-time constant) and
+SpockCorePatchsetVersion (runtime global) to the standard places
+PostgreSQL already uses for server-wide state.  No new files.
+
+--- a/src/include/miscadmin.h
++++ b/src/include/miscadmin.h
+@@ -540,4 +540,11 @@
+ /* in executor/nodeHash.c */
+ extern size_t get_hash_memory_limit(void);
+
++/*
++ * Spock core-patchset identity.  Bump the version when the patchset
++ * changes in a way visible to the extension binary.
++ */
++#define SPOCK_CORE_PATCHSET_VERSION 1
++extern PGDLLIMPORT int SpockCorePatchsetVersion;
++
+ #endif							/* MISCADMIN_H */
+--- a/src/backend/utils/init/globals.c
++++ b/src/backend/utils/init/globals.c
+@@ -120,6 +120,9 @@
+ bool		IsUnderPostmaster = false;
+ bool		IsBinaryUpgrade = false;
+
++/* Spock core-patchset identity. */
++int			SpockCorePatchsetVersion = SPOCK_CORE_PATCHSET_VERSION;
++
+ bool		ExitOnAnyError = false;
+
+ int			DateStyle = USE_ISO_DATES;