Skip to content

feat(forward): align contracts and complete resource APIs - #7

Merged
moonyue-w merged 1 commit into
mainfrom
codex/forward-api-parity
Oct 28, 2026
Merged

moonyue-w merged 1 commit into
mainfrom
codex/forward-api-parity

Conversation

@moonyue-w

Copy link
Copy Markdown
Contributor

Change

Java Forward callers currently need raw requests for resource Search, Dreams, Decision evaluation and Pairing management; typed Outcome rubrics also serialize the obsolete text field. This change adds 15 synchronous/asynchronous resource operations and updates the existing contracts against the official documentation checked on 2026-10-28.

  • Add four resource Search operations with body filters, Identity query scope, required Beta selectors and retained filters during pagination; five Dream operations; three Pairing management operations; and three Decision operations with preserved boolean/string choices and exact decimal scores.
  • Add Identity auto_memory_store, independent mount access and cursor pagination, Schedule file resources, optional Run input snapshots and Session event Credits accessors. Preserve the existing boxed mount hasMore() signature and raw event accessors.
  • Serialize text rubrics using content; retain the old text methods as deprecated aliases. Raw JSON callers must migrate the old key themselves.
  • Merge __qca_sdk_created, __qca_sdk_language=java and the actual JAR version into typed Session creation. Preserve custom metadata and caller maps; reject conflicting exact reserved keys before HTTP. These three entries count toward the service metadata limit.

The Forward inventory now includes 146 HTTP operations plus Realtime WebSocket, including the previously merged, unreleased Webhook work. Official contract links, migration notes and API coverage are in docs/forward-parity.md and docs/forward-api-coverage.md. An executable example and independent JAR consumer tests cover the new surface. Go/Python/TypeScript are unchanged; Managed is outside this Java Forward change.

Validation

  • SDK build, tests and Javadoc pass.
  • Independent examples consume the installed JAR and pass.
  • Java 8 package checks pass on Java 8, 11, 17, 21 and 25.
  • Documentation and Unreleased changelog reflect the behavior and migration.
  • make quality passes on JDK 17: formatting, repository/link checks and 38 maintenance tests.
  • Version change: not applicable to this feature PR; both POMs remain 0.1.0. Publishing requires a separate new-version PR.

For each of Java 8 / 11 / 17 / 21 / 25, ran these commands against the same frozen source snapshot:

./mvnw -B -ntp clean install
./mvnw -B -ntp -f examples/pom.xml clean verify
python3 .github/scripts/check_package.py

Each runtime passed 686 SDK tests and 67 independent consumer tests, with zero failures, errors or skips: 3,765 test executions across the matrix. Package checks include the main, sources and Javadoc JARs and Java 8 bytecode. The committed files match the tested snapshot hashes.

Also ran python3 .github/scripts/check_central_bundle.py on JDK 17. Disposable-key signing and SDK/POM/sources/Javadoc digest comparison passed; Central upload was skipped by the signing-only build. No package was published.

Regression coverage includes all 15 operations through sync/async and response wrappers, empty POST search, opaque/repeated cursors, backward mount pagination, query ownership, Beta/header retention, cancellable page fetches, exact numeric types, Decision request-byte/idempotency preservation, non-retried conflicts, metadata collisions and immutability, and current Outcome/Schedule wire fields.

No new live CN/Global scenarios, real channel pairing or Dream execution were run. Internal integration, pipeline QA-package acceptance and human approval remain separate follow-up gates; these offline checks are not production verification.

@moonyue-w
moonyue-w merged commit 68f810f into main Oct 28, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant