fix(sql): stabilize 0.3 named arguments

[NikolayS]

Summary

• expose stable named arguments for all 13 public partition/idempotency signatures
• migrate only exact alpha i_* contracts, then preserve stable OIDs and dependencies on reinstall
• retain ownership and effective reader/writer/admin grants
• add exhaustive named-call coverage and a real v0.3.0-alpha.1 → HEAD upgrade lane

Fixes #310.

Stack

• base: fix(partition-keys): make slot setup atomic #336 (agent/fix-partition-setup)
• fix(partition-keys): make slot setup atomic #336 → fix(partition-keys): make claims nonblocking #321 → fix(partition-keys): fence lease release #311

Validation

• fresh named-call contract passed on PostgreSQL 14, 17, and 19beta1
• v0.3.0-alpha.1 → HEAD preserved 12 migrated owners/grants plus partition/idempotency state
• stacked fix(partition-keys): make slot setup atomic #336 → HEAD migrated all 13 old-name OIDs
• stable HEAD reinstall preserved all 13 OIDs, a dependent view, owners, and grants
• v0.1.0 → HEAD passed on PG14 and PG19beta1
• full PG17 regression and acceptance suites passed
• public-execute, upgrade-grant, roles, and install-idempotency checks passed
• deterministic generator/assembly/TLE packaging and git diff --check passed

An alpha installation with user objects depending on an old i_* signature fails the one-time migration safely (no CASCADE); recreate that dependency after upgrading. Stable-name dependencies survive subsequent reinstalls.

[NikolayS]

REV rubric review

This is a manual execution of the repository's five applicable REV rubrics because the automated ultrareview quota was unavailable. It is not bot output. SOC2 was omitted.

• Bug/security: alpha-name migration is fail-closed for dependents. The final head also guards oversized alpha state before installing the 256-slot constraint; the former stack conflict is resolved by synchronization with #336.
• Tests: dependent-object, stable OID/grant, reinstall, named-call, and oversized-alpha upgrade paths are covered. f215a06 precedes 52e7af1; CI is 18/18 green.
• Docs/guidelines: current migration explanation is actionable. Historical test:/style: conflict with the repo list, and the style subject is 53 characters.

Blocking patch findings: none. Merge-order constraint: this PR is stacked on #336 and therefore follows #311 → #321 → #336. Preserve history, use a compliant squash/merge subject, and post exact upgrade evidence before merge. This COMMENT review is not an approval.

[NikolayS]

Real-user verification evidence for final head 8c9f656e4125fae953f1ada511a6032670508ca2, tested with the complete #311 -> #321 -> #336 stack.

Fresh-install and stable-reinstall coverage used:

PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --set=ON_ERROR_STOP=1 \
  --file=devel/sql/pgque.sql
PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --set=ON_ERROR_STOP=1 \
  --file=tests/test_named_arguments_v0_3.sql
PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --set=ON_ERROR_STOP=1 \
  --file=tests/test_named_arguments_v0_3_reinstall_fixture.sql
PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --set=ON_ERROR_STOP=1 \
  --file=devel/sql/pgque.sql
PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --set=ON_ERROR_STOP=1 \
  --file=tests/test_named_arguments_v0_3_reinstall_assertions.sql

The pre-fix named-argument contract failed with old internal names:

ERROR: pgque.ack_partitioned(text,text,integer,integer,text) input names:
expected {queue_name,consumer,slot,n,worker}, got {i_queue,i_consumer,i_slot,i_n,i_worker}

The head passed all 13 public signatures and stable reinstall identity/dependency checks:

PASS: stable named arguments for all 0.3 public APIs
PASS: stable reinstall preserved named API identities and dependency

The real alpha upgrade path began from the tagged artifact and ran transactionally:

git show v0.3.0-alpha.1:devel/sql/pgque.sql \
  | PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --set=ON_ERROR_STOP=1
PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --set=ON_ERROR_STOP=1 \
  --file=tests/test_upgrade_v0_3_alpha_fixture.sql
PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --single-transaction \
  --set=ON_ERROR_STOP=1 --file=devel/sql/pgque.sql
PAGER=cat psql --no-psqlrc "$PGQUE_TEST_DSN" --set=ON_ERROR_STOP=1 \
  --file=tests/test_upgrade_v0_3_alpha_assertions.sql

It preserved partition/idempotency state, owners, effective grants, and migrated function identities:

PASS: alpha named-argument upgrade preserved state, owners, and grants

Two failure preflights were exercised as failed single-transaction upgrades, followed by state assertions and successful retry.

1. A view depending on an alpha i_* function initially caused PostgreSQL's opaque cannot drop function ... because other objects depend on it. The chronological fix now fails before mutation with:

ERROR: cannot stabilize named arguments for pgque.send(text,text,jsonb,text) because dependent objects exist: rule _RETURN on view upgrade_v03_named_dependency. PostgreSQL cannot rename input parameters in place; drop these dependents, run the transactional upgrade, then recreate them
PASS: blocked alpha rename preserved function, dependency, and state

After dropping the named dependent view, the same transactional upgrade and alpha assertions succeeded. The failed attempt preserved the old function OID/input names, the dependent view, queue/subscription state, and the pending event.

2. An alpha consumer persisted with n=257 initially reached a generic table CHECK violation. The chronological fix now fails before DDL with:

ERROR: cannot upgrade partitioned consumer oversized-workers on queue upgrade_v03_oversized_q with n=257: 0.3 supports at most 256 slots; drop and recreate it with n <= 256, then retry the transactional upgrade
PASS: oversized alpha upgrade failed without changing state

The failed attempt preserved the alpha function OID, partition metadata, slot, subscription, and pending event. After explicitly removing/recreating that alpha consumer within the supported ceiling, the transactional upgrade, named-argument suite, slot-ceiling test, security/grants/roles checks, stable reinstall, full regression, and acceptance suites all passed.

RED/GREEN chronology: mixed. The original named-argument stabilization is retrospective (independent base RED/head GREEN replay, not a test-first commit sequence). The dependency preflight is chronological RED 96073f8 -> GREEN fa880e3. The oversized-alpha preflight is chronological RED f215a06 -> GREEN 52e7af1.

Final full CI after synchronizing the stacked base: 18/18 checks passed, including the v0.3.0-alpha.1 -> HEAD lane on PG17 and PostgreSQL 14-19beta1.

Readiness-race transparency: an earlier full run on the same pre-stack-sync feature SHA, run 29156128594, had only stable install smoke (frozen sql/) fail on attempt 1. pg_isready observed PostgreSQL 19beta1's temporary initdb server, then the client connected while the container entrypoint restarted it. Frozen sql/ was unchanged. The approved failed-job rerun on the same SHA passed (attempt 2); the final post-stack-sync run above passed the stable smoke on its first attempt. The readiness fix is tracked separately in #337 and was not duplicated into this SQL PR.

This comment records test evidence only; it is not a review or merge decision.