[V1] Defines PSink and IonSink to encode PartiQL data with type-annotated Ion.

[RCHowell]

Draft

This is a draft because it is not complete, the remaining items are

• datetimes
• structs
• rows
• variants

Most are easy, but datetimes is blocked on #1656

Description

This PR adds a source and sink API to the SPI package which will become the backing interfaces for various PartiQL encoding schemes (firstly Ion). These APIs are just like the reader/writer APIs from IonJava, but are intended to be extended to get values into a PartiQL system. The primary/default application here will be to encode PartiQL data in typed Ion.

See #1654 and #1655

The tests and streams.md have a description of the design and decisions there. I have gone back and forth many times, and prefer the per-sink type decorators and elisions, and the DatumWriter doing materialization along with settting the type context just like the IonWriter type annotations.

Other Information

• Updated Unreleased Section in CHANGELOG: NO
• Any backward-incompatible changes? NO
• Any new external dependencies? NO
• Do your changes comply with the Contributing Guidelines
  and Code Style Guidelines? YES

License Information

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 80.03%. Comparing base (d059c81) to head (d94a4af).
Report is 443 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #1687      +/-   ##
============================================
+ Coverage     73.16%   80.03%   +6.87%     
+ Complexity     2393       47    -2346     
============================================
  Files           247       19     -228     
  Lines         17627      506   -17121     
  Branches       3178       23    -3155     
============================================
- Hits          12896      405   -12491     
+ Misses         3854       88    -3766     
+ Partials        877       13     -864     

Flag	Coverage Δ
CLI	?
EXAMPLES	80.03% <ø> (-0.04%)	⬇️
LANG	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[github-actions]

CROSS-ENGINE-REPORT ❌

	BASE (LEGACY-V0.14.8)	TARGET (EVAL-3708BFF)	+/-
% Passing	89.67%	94.32%	4.65% ✅
Passing	5287	5561	274 ✅
Failing	609	54	-555 ✅
Ignored	0	281	281 🔶
Total Tests	5896	5896	0 ✅

Testing Details

• Base Commit: v0.14.8
• Base Engine: LEGACY
• Target Commit: 3708bff
• Target Engine: EVAL

Result Details

• ❌ REGRESSION DETECTED. See Now Failing/Ignored Tests. ❌
• Passing in both: 2641
• Failing in both: 17
• Ignored in both: 0
• PASSING in BASE but now FAILING in TARGET: 5
• PASSING in BASE but now IGNORED in TARGET: 108
• FAILING in BASE but now PASSING in TARGET: 180
• IGNORED in BASE but now PASSING in TARGET: 0

Now FAILING Tests ❌

The following 5 test(s) were previously PASSING in BASE but are now FAILING in TARGET:

Click here to see

1. undefinedUnqualifiedVariableWithUndefinedVariableBehaviorMissing, compileOption: PERMISSIVE
2. undefinedUnqualifiedVariableIsNullExprWithUndefinedVariableBehaviorMissing, compileOption: PERMISSIVE
3. undefinedUnqualifiedVariableIsMissingExprWithUndefinedVariableBehaviorMissing, compileOption: PERMISSIVE
4. inPredicateWithTableConstructor, compileOption: PERMISSIVE
5. notInPredicateWithTableConstructor, compileOption: PERMISSIVE

Now IGNORED Tests ❌

The complete list can be found in GitHub CI summary, either from Step Summary or in the Artifact.

Now Passing Tests

180 test(s) were previously failing in BASE (LEGACY-V0.14.8) but now pass in TARGET (EVAL-3708BFF). Before merging, confirm they are intended to pass.

The complete list can be found in GitHub CI summary, either from Step Summary or in the Artifact.

CROSS-COMMIT-REPORT ✅

	BASE (EVAL-B0403E6)	TARGET (EVAL-3708BFF)	+/-
% Passing	94.32%	94.32%	0.00% ✅
Passing	5561	5561	0 ✅
Failing	54	54	0 ✅
Ignored	281	281	0 ✅
Total Tests	5896	5896	0 ✅

Testing Details

• Base Commit: b0403e6
• Base Engine: EVAL
• Target Commit: 3708bff
• Target Engine: EVAL

Result Details

• Passing in both: 5561
• Failing in both: 54
• Ignored in both: 281
• PASSING in BASE but now FAILING in TARGET: 0
• PASSING in BASE but now IGNORED in TARGET: 0
• FAILING in BASE but now PASSING in TARGET: 0
• IGNORED in BASE but now PASSING in TARGET: 0