[Pino de Candia (pinodeca)]

Summary

Add a fixed, 154-case regression corpus for nested durable SQL function shapes,
adapted from Prashant Chinnam (Prashant Chinnam (@crprashant))'s work in #234 and the testing proposal
in #232. This PR does not modify #234 or its author's fork.

The corpus covers depth-2 compositions of sequences, conditionals, loops, joins,
and races, plus explicit else-branch and break-loop cases. Each case stores its
complete DSL definition and expected per-path marker counts in
tests/e2e/shapes/manifest.json.

Design

• Fixed manifest: definitions and expectations are committed test data.
  No shape generator is included or required.
• Small Python runner: validates the manifest and supplies standalone SQL
  wrappers for setup, submission, completion checks, assertions, and cleanup.
  It does not enumerate shapes, calculate expectations, or rewrite the manifest.
• Shared SQL fixture: public.df_gen_mark(shape_id, node_path) inserts a
  trace row and returns its per-marker execution ordinal. Calls execute when
  the worker reaches the corresponding SQL node, not during graph construction.
• Existing harness integration: --include-shapes adds the corpus to the
  E2E selection, retaining per-case filtering, repeated runs, and PASS/FAIL
  reporting. SQL wrappers live in a private temporary directory removed on exit.
• CI coverage: the fixed_matrix job validates the corpus and tests the
  runner without PostgreSQL. The existing PostgreSQL test job depends on that
  check and executes the corpus alongside the handwritten E2E suite.

The helper and trace table are persistent fixtures in the test database, owned
by df_e2e_user, not extension objects. Each wrapper sets them up before
submission. The helper uses invoker privileges, a fixed pg_catalog search path,
and a schema-qualified table reference; corpus calls and trace reads are also
schema-qualified.

The README provides self-contained documentation of marker paths, the corpus
construction algorithm, fixture behavior, and maintenance.

What the tests establish

Every instance must complete successfully. The runner then compares trace-table
row counts with the explicit expectation for each path, including zero counts,
and rejects unexpected or NULL paths.

These are observable SQL side effects, not counts inferred from extension
monitoring metadata. They detect missing, duplicate, or incorrectly selected
marker work. Counter markers provide loop termination independently of the
number of markers inside a loop body.

Scope and limitations

Test infrastructure only: no production Rust, extension SQL/API, extension
version, root dependency, or upgrade-script changes.

• Counts do not establish causal ordering, arbitrary SQL semantics, or general
  return-value correctness.
• Execution is sequential, with a 60-second completion timeout per case.
• Race cases assume the intended winner finishes before the losing branch's
  30-second delay; this is not a scheduling guarantee under load.
• Trace tags isolate different shapes, not simultaneous runs of the same shape.
  Do not run two copies against one database.
• Manifest validation checks structure, not semantic correctness; definitions
  and expectations require review.

Run locally

Requires Python 3.9+ with no third-party Python packages.

python3 tests/e2e/shapes/runner.py --check
python3 -m unittest discover -s tests/e2e/shapes -p 'test_*.py'
./scripts/test-e2e-local.sh --include-shapes gen-

Use gen-0076 instead of gen- to select one case. Omit the filter to include
the handwritten E2E suite.

Validation

• Full helper-backed live PG17 corpus: 154 passed, 0 failed.
• 12 unit/CLI tests pass, covering manifest validation, malformed input,
  duplicate keys/IDs, preserved definitions and expectations, all 552 marker
  calls, fixture setup, deterministic wrappers, output errors, and read-only
  manifest handling.
• 2 optional live runner tests pass, covering assertion failures, helper
  ordinals, shape/path isolation, shadow-table resistance, invoker mode, and
  recorded integer activity output. They skip unless a live database is
  explicitly configured.
• Targeted gen-0076 passes through --include-shapes.
• Filtering, repeated/verbose runs, no-match errors, and temporary-file
  cleanup verified.
• Standalone manifest validation and unit/CLI tests pass outside a Git
  checkout, with no repository history available.
• Shell syntax, extension formatting, and git diff --check pass.

The full handwritten E2E suite, full upgrade suite, and PG18 corpus were not
run locally for this change. Required CI and human review remain merge gates.

Upgrade & Migration

The B1 supported-schema contract is unchanged. No upgrade DDL or runtime schema
detection is needed.

These tests start fresh instances; they do not exercise crash recovery or old
persisted histories. Curated predecessor-compatible shapes in #409's N-1/B1/B2
upgrade lifecycle belong in a separate PR.

Attribution

Adapted from #234 by Prashant Chinnam (@crprashant). The commit credits:

Co-authored-by: Prashant Chinnam 5108573+crprashant@users.noreply.github.com
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com