From f8a584ac9e22e3f2a6d3a998ac1189b90ab582a2 Mon Sep 17 00:00:00 2001 From: Dotta Date: Sun, 9 Aug 2026 02:20:29 +0000 Subject: [PATCH] docs(runner): clarify phase 6 port ownership Co-Authored-By: Paperclip --- packages/paperclip-runner/docs/architecture.md | 5 +++-- .../docs/design/phase-6-thin-paperclip-adapter.md | 7 +++++++ .../spec/paperclip-native-runner-implementation-plan.md | 3 ++- 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/packages/paperclip-runner/docs/architecture.md b/packages/paperclip-runner/docs/architecture.md index 3ad2825e1ca..82f57155f5a 100644 --- a/packages/paperclip-runner/docs/architecture.md +++ b/packages/paperclip-runner/docs/architecture.md @@ -206,6 +206,7 @@ buildable, testable, and runnable against the mock adapter. The proposed Phase 6 seam is recorded in [Phase 6 Thin Paperclip Adapter Boundary](design/phase-6-thin-paperclip-adapter.md). It keeps one dependency direction, branches only after Paperclip workspace and -environment realization, uses a server-bound implementation of the public -ports, and returns to the existing Paperclip finalization path. The proposal is +environment realization, composes a package-owned `NativeSessionBackend` with +a server-bound `ControlPlanePort`, and returns to the existing Paperclip +finalization path. The core seam contains no runner behavior. The proposal is design-only until the CTO gate accepts it. diff --git a/packages/paperclip-runner/docs/design/phase-6-thin-paperclip-adapter.md b/packages/paperclip-runner/docs/design/phase-6-thin-paperclip-adapter.md index c5d4e8a3cf3..d0915493356 100644 --- a/packages/paperclip-runner/docs/design/phase-6-thin-paperclip-adapter.md +++ b/packages/paperclip-runner/docs/design/phase-6-thin-paperclip-adapter.md @@ -13,6 +13,13 @@ Paperclip will integrate the native runner through two public package ports: - `ControlPlanePort` accepts validated PRP events and terminal results from the package and exposes durable acknowledgement and replay cursors. +The two ports are complementary, not two core implementations. The runner +package supplies the `NativeSessionBackend` implementation; Paperclip supplies +the server-bound `ControlPlanePort` implementation. The core adapter only +composes those public contracts and translates the final result into existing +Paperclip types. It does not implement a native backend or contain runner +behavior. + The dependency direction is one way: ```text diff --git a/packages/paperclip-runner/spec/paperclip-native-runner-implementation-plan.md b/packages/paperclip-runner/spec/paperclip-native-runner-implementation-plan.md index 5c9ba5ae067..9816013e20c 100644 --- a/packages/paperclip-runner/spec/paperclip-native-runner-implementation-plan.md +++ b/packages/paperclip-runner/spec/paperclip-native-runner-implementation-plan.md @@ -425,7 +425,8 @@ No Phase 6 implementation code starts until the CTO gate accepts that record. **Deliverables:** -- Paperclip implementation of `ControlPlanePort`/`NativeSessionBackend` in a narrow integration package or service boundary; +- a package-owned `NativeSessionBackend`, a server-bound Paperclip + `ControlPlanePort`, and a narrow core seam that only composes them; - feature-flagged runtime selection; - mapping to existing workspace preparation/finalization, cancellation, budgets, approvals, audit, and issue status authority; - native event persistence/replay adapter using the proven schema;