feat: finalize portable packet and serializer runtime surface

Author: M1hono

README.MD

@@ -9,15 +9,21 @@
 1. 给一个状态类写持久化和同步结构；
 2. 给一个 packet 写稳定 id、版本和 decode 逻辑；
 3. 给某个类型提供统一 serializer；
-4. 在运行时按 authored class 取回对应的 schema binding 或 packet binding。
+4. 在运行时直接按类型保存、读取状态或 packet。
 
-大多数作者平时只会接触三层东西：
+平时常用的只有三层东西：
 
 1. 注解：`@PiSyncModel`、`@PiField`、`@PiPacket`
 2. 运行时入口：`PiSchemas`、`PiPackets`、`PiSerializeServices`
 3. 少量 serializer API：`PiSerializer`、`PiSerializers`
 
-你通常不需要手写或直接依赖 `_PiSchema`、`_PiPacket` 这类 generated class。
+你通常不需要手写或直接依赖 `_PiSchema`、`_PiPacket` 这类 generated class，也不该把 `binding.codec()` 当作第一层日常用法。
+
+常见分层可以这样理解：
+
+1. `api.*` 下面是你平时直接写代码会碰到的注解和契约
+2. `PiSchemas`、`PiPackets` 是 runtime lookup 入口
+3. `PiNet` 会直接消费这里生成出来的 packet id、version 和 codec
 
 ## 典型用法
 
@@ -34,18 +40,18 @@ public final class ManaState {
 }
 ```
 
-运行时你拿到的是 binding，而不是自己去找 generated class：
+最直接的用法是按类型直接保存和读取：
 
 ```java
-PiStateBinding<ManaState> binding = PiSchemas.require(ManaState.class);
-
-CompoundTag full = binding.saveFull(state);
-binding.loadFull(restored, full, PiDecodeContext.strict());
+CompoundTag full = PiSchemas.saveFull(state);
+ManaState restored = PiSchemas.loadFull(ManaState.class, full);
 ```
 
-如果你只想写默认 client view、persisted view 或 delta，也都走 binding：
+如果你需要 client view、persisted view、delta 这种更细的控制，再下到 binding：
 
 ```java
+PiStateBinding<ManaState> binding = PiSchemas.require(ManaState.class);
+
 CompoundTag clientView = binding.saveClientView(state);
 CompoundTag persisted = binding.savePersisted(state);
 CompoundTag delta = binding.writeClientDelta(state, dirtySet);
@@ -75,23 +81,30 @@ public final class CastSkillPacket extends PiServerPacket {
         this.skill = skill;
         this.level = level;
     }
-
-    @Override
-    protected void handle(PiServerPacketContext context) {
-    }
 }
 ```
 
-运行时同样按 authored class 或稳定 id 取 binding：
+大多数时候，写完这个类就够了。`PiSerializeKit` 这边主要负责让这个 packet 有稳定 id、版本和 decode 逻辑，`PiNet` 会直接接住这层结果去做注册和收发。
+
+这里的 `@PiField(sync = ...)` 只是为了让 packet 字段和 schema 字段复用同一套字段描述；route、tracking、broadcast 这些发送语义还是由上层网络层决定。
+
+如果你在做调试、桥接或底层 transport 接线，也可以直接按类型编解码：
 
 ```java
-PiPacketBinding<CastSkillPacket, ?> binding = PiPackets.require(CastSkillPacket.class);
-FriendlyByteBuf buf = new FriendlyByteBuf(Unpooled.buffer());
+CastSkillPacket packet = new CastSkillPacket("fireball", 2);
+FriendlyByteBuf raw = new FriendlyByteBuf(Unpooled.buffer());
+PiPacketBuffer buffer = PiPacketBuffers.wrap(raw);
 
-binding.codec().write(buf, new CastSkillPacket("fireball", 2));
-CastSkillPacket decoded = binding.codec().read(buf);
+PiPackets.write(buffer, packet);
+raw.readerIndex(0);
+
+ResourceLocation id = packet.packetId();
+int version = packet.version();
+CastSkillPacket decoded = PiPackets.read(CastSkillPacket.class, buffer);
 ```
 
+只有在你需要查 binding、字段列表、版本或 migration 信息时，才需要再下到 `PiPackets.require(...)`。
+
 ### 3. 安装或临时覆盖 serializer runtime
 
 如果你只是要 built-in serializer：
@@ -102,6 +115,12 @@ PiBuiltInSerializers.install(runtime);
 PiSerializeServices.install(runtime);
 ```
 
+这几个类的实际位置是：
+
+1. `org.pickaid.piserializekit.runtime.service.PiSerializeRuntime`
+2. `org.pickaid.piserializekit.runtime.service.PiBuiltInSerializers`
+3. `org.pickaid.piserializekit.api.service.PiSerializeServices`
+
 如果你只是想在某个局部逻辑里临时切换 runtime：
 
 ```java
@@ -112,9 +131,9 @@ PiSerializeServices.withScope(runtime, () -> {
 
 这个 scoped override 很适合测试、局部覆盖或上层 pack 做隔离策略。
 
-## 你实际会依赖哪些 API
+## 更底层时再用这些 API
 
-稳定的作者侧入口主要是这些：
+平时常用入口主要是这些：
 
 1. `org.pickaid.piserializekit.api.schema.*`
 2. `org.pickaid.piserializekit.api.packet.*`
@@ -124,49 +143,23 @@ PiSerializeServices.withScope(runtime, () -> {
 6. `PiPackets`
 7. `PiSerializeServices`
 
-下面这些默认按内部实现处理，不建议下游直接写死依赖：
+如果你需要更多控制，再下到：
+
+1. `PiStateBinding`
+2. `PiPacketBinding`
+3. `PiDecodeContext`
+4. `PiSerializer`
 
-1. `processor.*`
-2. `processor.support.*`
-3. `processor.model.*`
-4. `runtime.*.support`
-5. `runtime.*.codec`
-6. generated class 名字本身
+这些更多是高级入口，不应该成为最先展示的日常写法。
 
-## 作者侧规则
+## 使用规则
 
 第一次写 `@PiSyncModel` / `@PiPacket` 前，先记住这些硬规则：
 
 1. `@PiSyncModel.version` 和 `@PiPacket.version` 必须 `>= 1`
 2. schema id 和 packet id 在同一轮编译里必须唯一
-3. `@PiSyncModel`、`@PiPacket`、`@PiLivingService` 必须是 top-level concrete class
+3. `@PiSyncModel`、`@PiPacket` 必须是 top-level concrete class
 4. `@PiSyncModel` 需要可访问的无参构造器，而且不能声明 checked exception
 5. `@PiPacket` 的 decode 构造器必须和 `@PiField` 顺序一致，而且不能声明 checked exception
 6. `@PiField(serializer = ...)` provider 需要可访问的无参构造器，而且不能声明 checked exception
 7. `@PiAfterDecode`、`@PiSchemaUpgrade`、`@PiPacketUpgrade` 方法不能声明 checked exception
-
-## 这个库不负责什么
-
-这些事不属于 `PiSerializeKit`：
-
-1. channel 安装、发送目标、线程切换、transport guard
-2. capability / host runtime 绑定
-3. gameplay service 生命周期
-4. UI、render、world 的高层 author magic
-5. 黑盒反射式自动读写
-
-换句话说：
-
-1. `PiSerializeKit` 负责数据如何描述、升级、诊断、绑定
-2. `PiNet` 负责 packet 如何发送、路由、守卫
-3. `Pibrary` 和后续 packs 负责这些 schema / packet 如何进入实际 gameplay host
-
-## 验证
-
-这个仓库当前把下面这条命令当作最低冷验证门槛：
-
-```bash
-bash ./gradlew clean test --no-daemon
-```
-
-仓库里也有 `.github/workflows/ci.yml`，会在 GitHub 上跑同一条 `clean test`。

README_EN.md

@@ -9,15 +9,21 @@ Use it when you need any of these:
 1. a typed state model that can be saved and synced;
 2. a packet with a stable id, version, and decode path;
 3. a reusable serializer for one Java type;
-4. runtime lookup from an authored class to its generated schema or packet binding.
+4. direct runtime save/load helpers by type.
 
-Most authors only touch three layers:
+Most day-to-day code only touches three layers:
 
 1. annotations such as `@PiSyncModel`, `@PiField`, and `@PiPacket`;
 2. runtime entry points such as `PiSchemas`, `PiPackets`, and `PiSerializeServices`;
 3. serializer APIs such as `PiSerializer` and `PiSerializers`.
 
-You normally do not hand-reference `_PiSchema`, `_PiPacket`, or other generated companion names.
+You normally do not hand-reference `_PiSchema`, `_PiPacket`, or other generated companion names, and the low-level `binding.codec()` path should not be the first example most users see.
+
+The usual split is:
+
+1. `api.*` contains the annotations and contracts you write against most of the time;
+2. `PiSchemas` and `PiPackets` are the runtime lookup entry points;
+3. `PiNet` consumes the packet ids, versions, and codecs generated here.
 
 ## Typical usage
 
@@ -34,18 +40,18 @@ public final class ManaState {
 }
 ```
 
-At runtime you resolve the binding from the authored class:
+The direct path is now:
 
 ```java
-PiStateBinding<ManaState> binding = PiSchemas.require(ManaState.class);
-
-CompoundTag full = binding.saveFull(state);
-binding.loadFull(restored, full, PiDecodeContext.strict());
+CompoundTag full = PiSchemas.saveFull(state);
+ManaState restored = PiSchemas.loadFull(ManaState.class, full);
 ```
 
-The same binding also gives you projections and deltas:
+If you need projections, persisted views, or deltas, then step down to the binding:
 
 ```java
+PiStateBinding<ManaState> binding = PiSchemas.require(ManaState.class);
+
 CompoundTag clientView = binding.saveClientView(state);
 CompoundTag persisted = binding.savePersisted(state);
 CompoundTag delta = binding.writeClientDelta(state, dirtySet);
@@ -75,23 +81,30 @@ public final class CastSkillPacket extends PiServerPacket {
         this.skill = skill;
         this.level = level;
     }
-
-    @Override
-    protected void handle(PiServerPacketContext context) {
-    }
 }
 ```
 
-Again, runtime code resolves the binding from the authored class or stable id:
+Most of the time, defining the class is the main job. `PiSerializeKit` gives the packet a stable id, version, and decode path, and `PiNet` consumes that result for registration and transport.
+
+The `@PiField(sync = ...)` values on packet fields only reuse the shared field descriptor model. Delivery concepts such as tracking, broadcast, and reply are still chosen by the network layer above.
+
+If you are debugging, bridging another transport, or wiring low-level runtime code, you can still encode and decode it directly:
 
 ```java
-PiPacketBinding<CastSkillPacket, ?> binding = PiPackets.require(CastSkillPacket.class);
-FriendlyByteBuf buf = new FriendlyByteBuf(Unpooled.buffer());
+CastSkillPacket packet = new CastSkillPacket("fireball", 2);
+FriendlyByteBuf raw = new FriendlyByteBuf(Unpooled.buffer());
+PiPacketBuffer buffer = PiPacketBuffers.wrap(raw);
 
-binding.codec().write(buf, new CastSkillPacket("fireball", 2));
-CastSkillPacket decoded = binding.codec().read(buf);
+PiPackets.write(buffer, packet);
+raw.readerIndex(0);
+
+ResourceLocation id = packet.packetId();
+int version = packet.version();
+CastSkillPacket decoded = PiPackets.read(CastSkillPacket.class, buffer);
 ```
 
+Use `PiPackets.require(...)` only when you really need binding lookup, field metadata, version details, or migration details.
+
 ### 3. Install or scope a serializer runtime
 
 If you want the built-in serializers:
@@ -102,6 +115,12 @@ PiBuiltInSerializers.install(runtime);
 PiSerializeServices.install(runtime);
 ```
 
+Those classes live in:
+
+1. `org.pickaid.piserializekit.runtime.service.PiSerializeRuntime`
+2. `org.pickaid.piserializekit.runtime.service.PiBuiltInSerializers`
+3. `org.pickaid.piserializekit.api.service.PiSerializeServices`
+
 If you want a temporary override for one code path:
 
 ```java
@@ -112,9 +131,9 @@ PiSerializeServices.withScope(runtime, () -> {
 
 That scoped override is useful for tests, isolated local overrides, and higher-level packs that need their own serializer policy.
 
-## What you should depend on
+## Drop lower only when needed
 
-These are the main stable author-facing entry points:
+These are the main entry points used most of the time:
 
 1. `org.pickaid.piserializekit.api.schema.*`
 2. `org.pickaid.piserializekit.api.packet.*`
@@ -124,49 +143,23 @@ These are the main stable author-facing entry points:
 6. `PiPackets`
 7. `PiSerializeServices`
 
-These should currently be treated as internal implementation detail:
+If you need more control, the next layer down is:
+
+1. `PiStateBinding`
+2. `PiPacketBinding`
+3. `PiDecodeContext`
+4. `PiSerializer`
 
-1. `processor.*`
-2. `processor.support.*`
-3. `processor.model.*`
-4. `runtime.*.support`
-5. `runtime.*.codec`
-6. generated companion class names themselves
+That is the advanced path, not the main path most code should start from.
 
-## Authoring rules
+## Usage rules
 
 Before using `@PiSyncModel` or `@PiPacket`, keep these hard rules in mind:
 
 1. `@PiSyncModel.version` and `@PiPacket.version` must be `>= 1`
 2. schema ids and packet ids must stay unique within the same compilation
-3. `@PiSyncModel`, `@PiPacket`, and `@PiLivingService` must be top-level concrete classes
+3. `@PiSyncModel` and `@PiPacket` must be top-level concrete classes
 4. `@PiSyncModel` needs an accessible no-arg constructor with no checked exceptions
 5. packet constructors used for generated decode must match `@PiField` order and must not declare checked exceptions
 6. `@PiField(serializer = ...)` providers need an accessible no-arg constructor with no checked exceptions
 7. `@PiAfterDecode`, `@PiSchemaUpgrade`, and `@PiPacketUpgrade` methods must not declare checked exceptions
-
-## What this repo does not do
-
-`PiSerializeKit` does not own:
-
-1. channel installation, send targets, thread routing, or transport guards;
-2. capability or host-runtime wiring;
-3. gameplay service lifecycles;
-4. high-level UI, render, or world author magic;
-5. reflective black-box auto-read/write.
-
-In practice:
-
-1. `PiSerializeKit` owns how data is described, upgraded, diagnosed, and bound;
-2. `PiNet` owns how packets are transported, routed, and guarded;
-3. `Pibrary` and later packs own how schemas and packets enter real gameplay hosts.
-
-## Verification
-
-The minimum cold verification gate for this repo is:
-
-```bash
-bash ./gradlew clean test --no-daemon
-```
-
-The repo also ships `.github/workflows/ci.yml`, which runs the same `clean test` gate on GitHub.

src/main/java/org/pickaid/piserializekit/api/packet/PiBidirectionalPacket.java

@@ -1,12 +1,10 @@
 package org.pickaid.piserializekit.api.packet;
 
 /**
- * Base type for packets that may dispatch on either side.
+ * Base type for packets that may travel on either side.
  */
-public abstract class PiBidirectionalPacket {
+public abstract class PiBidirectionalPacket extends PiPacketBase {
     public final PiPacketDirection direction() {
         return PiPacketDirection.BIDIRECTIONAL;
     }
-
-    protected abstract void handle(PiPacketContext context);
 }

src/main/java/org/pickaid/piserializekit/api/packet/PiClientPacket.java

@@ -1,12 +1,10 @@
 package org.pickaid.piserializekit.api.packet;
 
 /**
- * Base type for clientbound packets on the common author path.
+ * Base type for clientbound packets on the common path.
  */
-public abstract class PiClientPacket {
+public abstract class PiClientPacket extends PiPacketBase {
     public final PiPacketDirection direction() {
         return PiPacketDirection.CLIENTBOUND;
     }
-
-    protected abstract void handle(PiClientPacketContext context);
 }

src/main/java/org/pickaid/piserializekit/api/packet/PiClientPacketContext.java

@@ -12,7 +12,7 @@
  * {@link PiPacketNamespace}, the path may be inferred from the class name, and
  * the version defaults to {@code 1}. Annotated packet types must also stay
  * top-level classes because generated companions are emitted as package-level
- * types beside the authored host. Constructors used by generated decode must
+ * types beside the declared host. Constructors used by generated decode must
  * stay accessible and must not throw checked exceptions because generated
  * bindings instantiate packets directly.</p>
  */