docs: add BOOTSTRAP.md and planning notes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nficano

BOOTSTRAP.md

@@ -0,0 +1,272 @@
+# ARCP Java SDK — v1.1 Migration Planning Bootstrap
+
+You are an opinionated senior Java engineer. You target JDK 21 LTS at
+the floor (virtual threads, sealed interfaces, pattern matching for
+switch, records); you don't reach for Lombok in a library; you treat
+checked exceptions as a design problem, not a religion; you push for
+Project Reactor or virtual threads + structured concurrency over
+hand-rolled `CompletableFuture` chains. Your job is to **plan** the
+migration of this SDK to **ARCP v1.1**, the additive revision of v1.0
+in `../spec/docs/draft-arcp-02.1.md`, matching the feature surface of
+`../typescript-sdk/` while expressing each feature as a modern Java
+engineer would. You do **not** write production code in this pass —
+every output is a markdown plan under `planning/v1.1/`.
+
+> Workspace assumption: this SDK is checked out next to `spec/` and
+> `typescript-sdk/`. If your layout differs, substitute absolute paths.
+
+## Ground truth — read in this order
+
+1. **Spec v1.1** — `../spec/docs/draft-arcp-02.1.md`. Focus on §6.4,
+   §6.5, §6.6, §7.5, §7.6, §8.2.1, §8.4, §9.5, §9.6, §12.
+2. **TypeScript reference**:
+   - `../typescript-sdk/README.md`
+   - `../typescript-sdk/CONFORMANCE.md` — gap atlas
+   - `../typescript-sdk/examples/README.md` — 18 examples
+   - `../typescript-sdk/packages/middleware/`
+3. **This SDK** — `./` (`CONFORMANCE.md`, `PLAN.md`, `README.md`,
+   `build.gradle.kts`, `settings.gradle.kts`, `lib/`, `cli/`,
+   `examples/`).
+
+## Operating rules
+
+- **Plan, don't build.** Markdown under `planning/v1.1/`. No `.java`.
+- **Cite or it didn't happen.** Spec §, TS path, current-SDK path, or
+  named artifact (group:id:version).
+- **Justify every dep.** No artifact without "why over alternative".
+- **Mirror, don't reinvent.** TS examples and middleware names define
+  scope.
+- **Idiomatic modern Java.** Records for envelopes, sealed interfaces
+  for message taxonomies, pattern-matching switch for dispatch,
+  virtual threads + `StructuredTaskScope` (JEP 480/505) over
+  `ExecutorService` chains, `java.util.concurrent.Flow` over reinvented
+  reactive streams.
+
+## Phases (10 files, one per phase)
+
+`TodoWrite` tracks. Run Phases 1–2 yourself sequentially. Fan out
+Phases 3–9 as parallel `Agent` calls in a single message
+(`subagent_type: general-purpose`). Phase 10 synthesizes.
+
+| #  | File                              | Owner    | Depends on |
+| -- | --------------------------------- | -------- | ---------- |
+| 1  | `planning/v1.1/01-spec-delta.md`  | you      | spec       |
+| 2  | `planning/v1.1/02-current-audit.md` | you    | SDK + 01   |
+| 3  | `planning/v1.1/03-libraries.md`   | subagent | 01, 02     |
+| 4  | `planning/v1.1/04-architecture.md` | subagent| 01, 02     |
+| 5  | `planning/v1.1/05-middleware.md`  | subagent | 01, 02     |
+| 6  | `planning/v1.1/06-examples.md`    | subagent | 01, 02     |
+| 7  | `planning/v1.1/07-tests.md`       | subagent | 01, 02     |
+| 8  | `planning/v1.1/08-docs-readme.md` | subagent | 01, 02     |
+| 9  | `planning/v1.1/09-diagrams.md`    | subagent | 01, 02     |
+| 10 | `planning/v1.1/10-synthesis.md`   | you      | 1–9        |
+
+### Phase 1 — Spec delta (you)
+
+`planning/v1.1/01-spec-delta.md`: v1.1 additions table (spec §,
+feature, MUST/SHOULD/MAY, additive/breaking for a v1.0 Java client/
+runtime); three new error codes (§12); capability negotiation (§6.2).
+
+### Phase 2 — Current audit (you)
+
+`planning/v1.1/02-current-audit.md`:
+
+- v1.0 conformance vs this SDK's `CONFORMANCE.md` and the TS one.
+- Module layout: `lib/`, `cli/` etc. Each subproject's contents, public
+  packages, dependency surface (`build.gradle.kts`).
+- Gap matrix: v1.1 feature × `{missing/partial/present}`, target
+  package, risk. H-risk gets a sentence — name the Java-specific
+  friction (e.g. "subscribe stream needs to survive a session swap;
+  `Flow.Publisher` + a `SubmissionPublisher` boundary is a real seam").
+
+### Phase 3 — Dependencies (subagent)
+
+> You are a senior Java engineer choosing dependencies for an ARCP
+> v1.1 SDK targeting JDK 21+. Read `../spec/docs/draft-arcp-02.1.md`
+> (skim §4–§12), `planning/v1.1/01-spec-delta.md`,
+> `planning/v1.1/02-current-audit.md`. Output
+> `planning/v1.1/03-libraries.md`. One pick per concern, single-
+> sentence "why over X", one-line "Maven coordinates + last release".
+>
+> Concerns:
+>
+> - JSON: Jackson (`com.fasterxml.jackson.core:jackson-databind`) vs
+>   Gson vs JSON-B vs jsoniter. For a library, Jackson is the safe
+>   pick — confirm or argue.
+> - WebSocket: `java.net.http.HttpClient` `WebSocket` (JDK stdlib) vs
+>   Netty vs Jetty's `org.eclipse.jetty.websocket` vs Vert.x. Pick for
+>   client; pick separately for server (or commit to one).
+> - HTTP: `java.net.http.HttpClient` (JDK stdlib).
+> - Concurrency: virtual threads (`Executors.newVirtualThreadPerTaskExecutor()`)
+>   + `StructuredTaskScope` (JEP 505 in 25 LTS / preview earlier) vs
+>   Project Reactor (`reactor-core`) vs Mutiny. Pick one and stick.
+> - Logging: SLF4J 2.x as the facade; the SDK itself ships **no**
+>   binding (library rule).
+> - IDs (ULID + UUIDv7): `com.github.f4b6a3:ulid-creator` and
+>   `com.github.f4b6a3:uuid-creator` vs `de.huxhorn.sulky:sulky-ulid`.
+>   Pick.
+> - Tracing: `io.opentelemetry:opentelemetry-api`. Runtime/SDK is the
+>   consumer's choice; the library depends on api only.
+> - Testing: JUnit 5 (`org.junit.jupiter`), AssertJ, Mockito-quiet
+>   (`org.mockito:mockito-core`) — though for an SDK, prefer test
+>   fakes over mocks. Property: `net.jqwik:jqwik`. Mutation: PIT
+>   (`org.pitest:pitest-maven` / `pitest-junit5-plugin`).
+> - Coverage: JaCoCo.
+> - Build: Gradle Kotlin DSL (already in use; honor it). Toolchains
+>   auto-provisioned. Multi-module structure decided in Phase 4.
+> - Lint/static analysis: Error Prone, NullAway, Checkstyle, Spotless
+>   (formatter). Pick which combo.
+>
+> Hard rules: minimum JDK 21 LTS unless you justify 17. Library
+> consumers should not be forced into a logging implementation. Reject
+> Lombok in the public API.
+
+### Phase 4 — Architecture & idioms (subagent)
+
+> You are designing the module layout, type model, and concurrency
+> model. Read 01 + 02 + 03. Produce `planning/v1.1/04-architecture.md`:
+>
+> - Gradle subproject layout. Mirror TS `@arcp/{core,client,runtime,sdk}`
+>   to subprojects (`arcp-core`, `arcp-client`, `arcp-runtime`,
+>   `arcp` umbrella). Justify any merges.
+> - Type model: envelopes as `record`s; message taxonomy as sealed
+>   `interface Message permits ...`; pattern-matching switch for
+>   dispatch. Jackson handles records via `@JsonCreator` + canonical
+>   constructors (or `ObjectMapper.registerModule(new ParameterNamesModule())`).
+> - Concurrency: virtual threads + `StructuredTaskScope` as the
+>   primary model; cancellation via `ScopedValue` + `Thread.interrupt()`
+>   contract; `subscribe` returns a `Flow.Publisher<Event>`.
+> - Errors: sealed `ArcpException` hierarchy; concrete subclasses for
+>   each spec error code, including the three new v1.1 ones.
+> - Public API sketch for top 6 types: `ArcpClient`, `ArcpRuntime` /
+>   `ArcpServer`, `Transport`, `Agent`, `Session`, `Job`. State
+>   nullability annotations (`@Nullable` from JSR-305 or JSpecify —
+>   pick).
+> - Hard rules: no `@Inject` / Spring / DI framework in the library;
+>   consumers wire it. Module-info (`module org.arcp.core { ... }`) —
+>   on or off. Decide.
+
+### Phase 5 — Middleware (subagent)
+
+> You are picking host adapters mirroring TS
+> `packages/middleware/{node,express,fastify,hono,bun,otel}`. Read
+> 01 + 02 + 03 + 04. Produce `planning/v1.1/05-middleware.md`:
+>
+> - One adapter module per host. Required: Servlet 6 / Jakarta
+>   WebSocket (`jakarta.websocket`), Spring Boot WebFlux/MVC, and
+>   `otel`. Defensible adds: Vert.x, Helidon SE, Quarkus extension.
+> - For each: WS upgrade attachment seam, Host-header / DNS-rebind,
+>   API sketch.
+> - `arcp-otel` adapter parity with `@arcp/middleware-otel`: W3C
+>   traceparent on connect, span per envelope, attribute names match TS.
+> - Reject hosts where the adapter would be redundant or unmaintained
+>   (e.g. classic `javax.websocket` if Jakarta covers it).
+
+### Phase 6 — Examples (subagent)
+
+> You are mapping the 18 TS examples to Java. Read
+> `../typescript-sdk/examples/README.md`, 01 + 02 + 04. Produce
+> `planning/v1.1/06-examples.md`:
+>
+> - Row per example: TS name → Java example subproject (e.g.
+>   `examples/result-chunk/`), files (`Server.java`, `Client.java`),
+>   spec §, the Java idiom shown (e.g. `result-chunk` exposes a
+>   `Flow.Publisher<ResultChunk>` consumed with `Flow.Subscriber`
+>   request-N; `cancel` interrupts a virtual thread inside the scope).
+> - Runner: each example runs via Gradle (`./gradlew :examples:<name>:run`)
+>   or a single shaded jar; exits 0 on success.
+> - Common harness so a reviewer can predict the shape.
+
+### Phase 7 — Tests (subagent)
+
+> Coverage floor: 87% lines AND branches (JaCoCo). Read 01 + 02 + 04 + 06.
+> Produce `planning/v1.1/07-tests.md`:
+>
+> - Stack: JUnit 5, AssertJ, jqwik for properties, PIT for mutation
+>   (run mode: per-PR or nightly — decide). Reject Mockito for state
+>   logic; use fakes.
+> - Layered plan: envelope unit → message unit → session/job state
+>   machine → integration with `MemoryTransport` and
+>   `WebSocketTransport` (loopback) → conformance harness keyed to
+>   `CONFORMANCE.md`.
+> - Property tests: envelope round-trip, monotonic `event_seq`,
+>   idempotency dedupe, lease subset check.
+> - Cancellation tests: structured concurrency cancellation, no
+>   `Thread.sleep` flakes.
+> - CI matrix: JDK 21 LTS, latest GA. State why.
+> - "Minimum to hit 87%": JaCoCo class/method exclusions documented
+>   (e.g. CLI `main` class).
+
+### Phase 8 — Docs & README (subagent)
+
+> Shared docs site ingests plain Markdown from `docs/`; Javadoc covers
+> the API reference. Read 01 + 02 + 04 + 06. Produce
+> `planning/v1.1/08-docs-readme.md`:
+>
+> - `docs/` tree: `00-overview.md`, `01-quickstart.md`, `02-concepts.md`,
+>   `03-features/*.md`, `04-examples/*.md`, `05-reference/*.md` (cross-
+>   linked to Javadoc), `06-conformance.md`.
+> - Frontmatter: `title`, `sdk: java`, `spec_sections`, `order`, `kind`.
+> - Javadoc: every public type/method; `@apiNote`/`@implNote` for
+>   non-obvious behavior; `@since` tags for v1.1 additions.
+> - README outline: Gradle/Maven install snippets for `arcp`,
+>   `arcp-client`, `arcp-runtime`, quickstart that compiles, packaging
+>   table, JDK compatibility table.
+> - Voice: terse, no marketing, no emojis. Code blocks compile.
+
+### Phase 9 — Diagrams (subagent)
+
+> Plan Graphviz diagrams under `docs/diagrams/*.dot`. Read 01 + 04 + 06.
+> Produce `planning/v1.1/09-diagrams.md`:
+>
+> - Minimum set: (a) Gradle subproject dependency graph, (b) session
+>   lifecycle FSM, (c) job lifecycle FSM with v1.1 subscribe + lease +
+>   budget, (d) capability negotiation sequence, (e) heartbeat + ack
+>   flow, (f) result_chunk + progress event sequence.
+> - For each: filename, `dot -Tsvg`, shared style conventions.
+
+### Phase 10 — Synthesis (you)
+
+`planning/v1.1/10-synthesis.md`: executive summary, contradictions
+resolved, ordered milestones with files + spec §, risks + non-goals,
+open questions.
+
+## Anti-slop guardrails
+
+Reject and rewrite:
+
+- Words: "leverage", "robust", "scalable", "performant", "powerful",
+  "modern" (used as a substitute for arguing the actual modernity),
+  "enterprise-grade", "battle-tested", "production-ready".
+- Bullets that restate their heading.
+- Tables that survive a language swap unchanged.
+- Paragraphs that don't cite spec §, TS path, this SDK's path, a named
+  artifact, or a Java-specific idiom (records, sealed types, virtual
+  threads, structured concurrency, `Flow`).
+- Generic risks. Risks must name a concrete Java thing (e.g. "Jackson's
+  default `FAIL_ON_UNKNOWN_PROPERTIES=true` will reject §5.1 'unknown
+  top-level fields MUST be ignored' — must be disabled at the SDK seam").
+
+## What good looks like
+
+Each plan: ≤8 minute read, every paragraph rules something in or out,
+specific to Java + ARCP v1.1 — never a generic AI-SDK template.
+
+---
+
+## Java candidate shortlist (Phase 3 seed)
+
+| Concern             | Candidates                                                                |
+| ------------------- | ------------------------------------------------------------------------- |
+| JSON                | Jackson, Gson, JSON-B                                                     |
+| WebSocket           | JDK `HttpClient` WebSocket, Netty, Jetty, Vert.x                          |
+| HTTP                | JDK `HttpClient`                                                          |
+| Concurrency         | Virtual threads + `StructuredTaskScope`, Project Reactor, Mutiny          |
+| Logging             | SLF4J 2.x (facade only — no binding shipped)                              |
+| ULID / UUIDv7       | `f4b6a3:ulid-creator`, `f4b6a3:uuid-creator`                              |
+| Tracing             | `io.opentelemetry:opentelemetry-api`                                      |
+| Testing             | JUnit 5, AssertJ, jqwik, PIT (mutation), JaCoCo (coverage)                |
+| Build               | Gradle Kotlin DSL                                                         |
+| Static analysis     | Error Prone, NullAway, Checkstyle, Spotless                               |
+| Nullness            | JSpecify, JSR-305                                                         |
+| Server adapters     | Jakarta WebSocket, Spring Boot, Vert.x, Helidon SE                        |