antiwire

A community port of Square Wire to pure Java, with no Kotlin in production scope. This repository holds the research, the reviewed project plan, the decision record, the execution backlog, and the implemented port: runtime, .proto parser, schema linker and loader, command-line compiler, and Java code generator, proven against a live relocated copy of upstream 7.1.0 by the verification battery in scripts/verify.sh (the earlier M0 spike record is kept as history in docs/m0-execution-ledger-2026-10-01.md). The plan was reviewed externally on 2026-09-29 and the maintainer decisions taken after that review are recorded in docs/decisions.md.

The original request

Verbatim from the project initiator:

I would like to start a porting of https://square.github.io/wire/ project to pure java, to avoid depending on kotlin. The goal is to start using it in the projects apicurio-registry and apache-kafka. We would like to keep the footprint minimal and it's of utttermost importance to pass the same test suite that the project passes, including an internal or an external one. Performance are another concern, but functional compatibility is the main one. Prepare an analysis for a project plan and backlog.

The idea in short

Wire 7.1.0 (tag object da24c33ee1fe772a7a04617018087f46f26d1708, commit 9f62097dfe4995b5709d001ca0187e30ca0530ef) is a Kotlin Multiplatform project. A clean consumer of its wire-schema artifact resolves kotlin-stdlib (1.7 MB), okio (0.4 MB, itself Kotlin), kotlinpoet, and guava; wire-runtime alone pulls only kotlin-stdlib and okio. Apicurio Registry consumes exactly one Wire artifact, wire-schema, for schema parsing and its Schema model, pinned at 6.4.0. Apache Kafka has no Wire dependency today, and trunk practice suggests its community would not accept the Kotlin chain, though the review found no primary written policy supporting that conclusion. The port delivers the JVM-relevant slice of wire-runtime (about 8.2k upstream Kotlin lines) and wire-schema (about 11.8k upstream Kotlin lines) as pure Java at Java 11 bytecode, built with Maven on JDK 17 or later. Production artifacts and their transitive dependencies contain no Kotlin; small reviewed pure-Java dependencies are allowed with their footprint measured, and Kotlin stays permitted for build and test tooling. The port must run every applicable upstream test case, including the full runtime and reflection suites and the protoc-compatibility oracle at the pinned tag, with upstream Kotlin tests kept as Kotlin under mechanical, individually reviewed adaptations: Kotlin cannot call Java declarations with named arguments, so those call forms are rewritten, and Java overload bridges may support some omitted-default calls; no scenario is weakened. Apicurio is the first acceptance target, reached through a limited, documented source migration on the Apicurio side; Kafka is a later, non-gating goal. Full evidence and reasoning are in the research report.

What is in this repository

• docs/research-wire-java-port-2026-09-29.md: the research report (confidence-rated, with pinned sources). It covers the Wire module inventory, the verified dependency chains, the observed Apicurio consumption surface, Kafka constraints, prior art, the test-suite strategy, the phased plan with gates, and the risk register.
• docs/decisions.md: the approved decision record: semantic target, compatibility contract, dependency and test-scope policy, exclusions, publication and authorization boundaries, performance and footprint policy, release prerequisites, and the open technical decisions assigned to M0.
• docs/compatibility-matrix.md: the public-surface inventory against observed Apicurio call sites (OPEN-3), kept current by its owning tasks.
• docs/m0-execution-ledger-2026-10-01.md: what the executed M0 spikes built, mapped onto the decision record and the re-scoped task criteria, with measured effort.
• wire-upstream-shaded/: a never-published test fixture holding a relocated copy of upstream wire-runtime-jvm 7.1.0 that serves as the live parity oracle. The canonical build command is mvn verify (plain mvn test cannot package the fixture; see BUILD.md and scripts/verify.sh for the full verification entry point).
• docs/plan-review.md: the durable disposition ledger of the 2026-09-29 external review; every finding is mapped to an applied planning correction, a task owner, or a recorded decision.
• backlog/: the execution backlog in Backlog.md format. Seven milestones (M0 spikes through M5 release, plus the m-12 adversarial-audit follow-up milestone), the execution tasks TASK-1 through TASK-29 with subtasks plus a separate plan-maintenance task, each with acceptance criteria and dependencies. The test-parity requirement becomes concrete gates: applicable upstream cases with tracked adaptations and complete case accounting (TASK-9, TASK-13), a pinned-tag parity runner that blocks CI and never counts pending cases as passed (TASK-14, TASK-15, TASK-16), and a security regression corpus (TASK-17). Release is gated on measured footprint, measured performance, and a demonstrated upstream-sync procedure.

What the review settled, and what is still open

Settled by the maintainer after the review (docs/decisions.md): functional and source compatibility with no precompiled Wire 6/7 ABI promise; limited Apicurio source migration approved as scope; every relevant test case mandatory with exclusions only for declared non-ported functionality; no Kotlin in production with reviewed pure-Java dependencies allowed and Kotlin allowed for build and test; Apicurio first and Kafka deferred; measured runtime and Apicurio schema-operation performance required before release, thresholds set only after baseline measurement; footprint reported as measured clean-consumer versus marginal numbers with no size promise; the upstream-sync procedure demonstrated on an already-published delta as a release prerequisite; groupId io.apicurio, resolved by maintainer directive on 2026-10-02 (DEC-8).

Still open, with named owners: the release itself. TASK-21 owns the final candidate: remeasurement against it (the footprint acceptance binds to c713e9a and the performance sessions to 82c3624, both older than later runtime changes), the same-candidate Apicurio revalidation, the remaining DEC-13 checks, and the maintainer's explicit approval to publish. Nothing is published. The 2026-10-06 adversarial delivery audit (backlog/docs/doc-1) filed its follow-ups in backlog milestone m-12; all of the original follow-ups are closed, and two later review follow-ups remain open (TASK-16.2.1, the ProtoTarget output-directory containment guard; TASK-29, ignoring Python bytecode caches in scripts). Kafka remains deferred by the maintainer (TASK-22).

Feedback welcome as GitHub issues on this repository, or however you prefer to reach the maintainer.

Release contract

The release candidate contract for the initial 0.1.0 (mechanical groundwork recorded; publish itself stays gated on explicit maintainer approval and the full DEC-13 release gate set: required CI green, a release-time recheck that published dependency metadata contains no Kotlin, the Java 11 consumer smoke run on the final candidate, the demonstrated upstream-sync procedure, and freshness of the measurement records against the final candidate's revision and checksums):

• Coordinates: groupId io.apicurio (DEC-8, resolved by maintainer directive 2026-10-02), artifacts wire-runtime-java, wire-schema-java, wire-java-generator. Separate artifacts with a transitive edge matching upstream (OPEN-2 resolved): schema depends on runtime, the generator is optional, and no runtime or schema consumer pulls generator dependencies. maven.deploy.skip stays true as a DEC-8 guard.
• Upstream pin: Square Wire tag 7.1.0, tag object da24c33e, resolved commit 9f62097dfe4995b5709d001ca0187e30ca0530ef, recorded in config/parity-pins.json and enforced by the parity runner.
• Java baseline: production bytecode is Java 11 (--release 11), built on JDK 17 or later (DEC-3).
• Dependency policy: wire-runtime-java has zero production dependencies (the okio buffer layer is vendored inside it under original package names; no okio artifact ships); wire-schema-java depends on the runtime only; wire-java-generator adds com.squareup:javapoet:1.13.0, the one third-party production dependency, pinned because every palantir javapoet release is Java 17 bytecode, which DEC-3 forbids, while Square JavaPoet reproduces the pinned upstream golden output up to the documented phase-2 Bytes mapping (DEC-3 rationale in the parent pom javapoet.version comment; docs/api-surface.md).
• Supported features: protobuf parsing, schema linking and pruning, dynamic messages, runtime encode/decode, the Java code generator and compiler CLI, and .proto emission through ProtoTarget (retained in scope by the 2026-10-06 maintainer decision, TASK-16.2; like upstream, reachable through the API, not a CLI flag). Excluded from the initial release (DEC-6): JSON adapters (gson, moshi), the gRPC client and wire-reflector, the Kotlin and Swift generators, the Gradle plugin, editions, and non-JVM targets. Generated Java models for protos using google.protobuf.Empty compile and round-trip against the port runtime since TASK-16.1: the generator maps Empty to ProtoAdapter.UnitValue fields carried by ProtoAdapter.WIRE_EMPTY, a bounded documented divergence from upstream's kotlin.Unit output, and the dynamic model represents Empty fields through the same singleton since TASK-26 (docs/api-surface.md, compatibility-matrix section E).
• Translation contract: the Kotlin-to-Java conventions every ported file follows are in docs/translation-conventions.md.
• License inventory: per-file notice audit of every shipped source and resource is in docs/license-inventory.md.
• Parity and measurement evidence: case accounting for the runtime, schema, and compiler suites in docs/task9-case-accounting.md, docs/task13-case-accounting.md, and docs/task16-case-accounting.md; footprint in docs/footprint.md; performance in docs/performance.md; the security regression corpus in docs/security-regression-inventory.md.
• Candidate procedure: scripts/release-build.sh packages the three shipped modules with sources and javadoc into target/release/ with a MANIFEST.sha256 and writes docs/release-candidate.md identifying the candidate (revision, date, wire pin) and the status of the two maintainer gates, open or recorded acceptance, for the footprint acceptance and the encodeForward performance finding (missing, reworded, ambiguous or reopened gate rows abort the build; --check-gates checks them alone, read-only). It performs no deploy, no tag, no publish. The copy committed at a45b0f0 (2026-10-02) is stale: it predates the gate closures (footprint c713e9a, accepted 2026-10-03, docs/footprint.md section 9.6; performance 82c3624, docs/performance.md session 5), and neither closure binds the final candidate. It is regenerated by TASK-21's final-candidate procedure.

License

The research and backlog are published under Apache 2.0, and the port is Apache 2.0 like upstream Wire. Upstream files carry mixed notices that are preserved verbatim, per file, including notices embedded in file bodies: five Wire files (the ProtoReader family, MathMethods, and ProtoWriter) carry BSD-style Google notices, the internal ArrayList files carry JetBrains Apache-2.0 notices, and any vendored okio code keeps its notices with separate Apache-2.0 attribution.