[FLINK-40541][table] Add on_time argument to SNAPSHOT for LATERAL SNAPSHOT join

[fhueske]

What is the purpose of the change

Add an explicit on_time DESCRIPTOR argument to the SNAPSHOT function that names the build-side row-time column. It replaces the implicit row-time inference: the argument is optional on the signature but required for streaming queries, and the planner resolves its field index and threads it through to the operator.

Because on_time is a reserved system-argument name, SNAPSHOT declares it while keeping the automatic system arguments disabled, and naming the column keeps a watermark hidden from SELECT * by column expansion available to the join. The LATERAL SNAPSHOT documentation is updated accordingly.

Brief change log

• add an on_time attribute to SNAPSHOT function to specify a rowtime attribute on the build-side input
  • pass index of rowtime attribute into join operator
  • operator implementation did not change
• change handling of PTF system-args
  • PTFs that disable system-args can now overwrite them (have args that are named like system-args)
• add just tests and documentation

Verifying this change

Run existing and new tests.

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): no
• The public API, i.e., is any changed class annotated with @Public(Evolving): no
• The serializers: no
• The runtime per-record code paths (performance sensitive): no
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: no
• The S3 file system connector: no

Documentation

• Does this pull request introduce a new feature? yes
• If yes, how is the feature documented? Adjusted the docs

---

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: Claude Opus 4.8 (1M context)

[flinkbot]

CI report:

• 37cc95d Azure: FAILURE

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot run azure re-run the last Azure build