ZLink Framework for Java/Kotlin -- Documentation

This set is the ZLink Framework documentation for Java, Kotlin, and Spring Boot. This directory holds internals/'s implementation and verification criteria, and the public contract lives in the central Java spec. Common meaning follows the common spec; here we give that meaning concrete shape on the Java/Kotlin surface.

The common meaning of async execution, CompletionStage, and the Kotlin coroutine wrapper follows the Async Execution And Coroutine Policy.

Sample and E2E config files, the ban on environment variables, and @ConfigurationProperties-binding criteria follow the Sample/E2E Configuration Policy.

Kotlin users should see the Kotlin-specific guide. zlink-framework-kotlin is a thin coroutine-idiom layer that shares this runtime. The contract used directly from Java follows the Java spec, and Kotlin-specific suspend/Flow contracts are fixed separately in the Kotlin spec. The Java usage guide will be rewritten at this location once the 11.0 public interface and samples are finalized.

Usage of the client libraries used separately from the server framework is found in the HTTP client guide and the Stream connector guide.

2. Public Contract Spec

The formal spec fixes the framework's target public contract first. Current Java/Kotlin implementation progress is not recorded in public contract documentation. The public contract for every framework language is managed together under spec/<package>/languages/.

Document	Scope
Spec table of contents	The list of Java/Kotlin public-contract documents
Java interfaces	The exact public signature per feature and the Spring host lifecycle
stream-connector	The client connector

The meaning and behavioral rules of a feature are owned by the common spec. Language-specific documents only fix what shape that meaning takes in Java/Kotlin.

3. Internal Criteria

internals/ explains implementation structure, lifecycle, and regression criteria for maintainers.

Document	Scope
backend-dependency-policy	Java binding dependency isolation
Common Internals	Runtime architecture decisions shared across all four languages
regression-test-matrix	JVM contract, E2E, and performance smoke criteria

4. Samples

Samples provide the same scenario set for both Java and Kotlin. The 6 canonical ones are per-app documents; feature-axis samples are kept as separate documents.

The 6 canonical samples' server roles, message contracts, state transitions, and completion criteria are owned by the common sample. The Java documents don't restate this contract.

Document	Scope
samples README	Java/Kotlin sample structure and how to run them