docs: record SDK migration design

superpowers/specs/2026-08-11-yoresee-doc-sdk-migration-design.md

@@ -0,0 +1,138 @@
+# Yoresee Doc SDK Migration Design
+
+## Goal
+
+Publish the protobuf-generated dependencies as two independent repositories under
+the `YoreseeDoc` Gitea organization and migrate the four services to consume
+those repositories:
+
+- `yoresee_doc_sdk_go` for Go protobuf and gRPC stubs.
+- `yoresee_doc_sdk_node` for browser ESM/Connect RPC stubs and Node.js CommonJS
+  gRPC stubs.
+
+The existing protobuf repository remains the single source of the `.proto`
+contract.
+
+## Scope
+
+This is a dependency migration, not a code-generation or CI/CD redesign.
+
+Included:
+
+- Generate and commit Go, ESM, and CommonJS artifacts in the two SDK repos.
+- Use the Gitea repositories as versioned service dependencies.
+- Change service imports to the SDK package paths.
+- Change the protobuf `go_package` to the canonical Go SDK module path.
+- Add package documentation describing the generated outputs and source proto.
+
+Explicitly unchanged:
+
+- `deploy/script/gen_proto.sh`.
+- Existing Dockerfiles and Docker Compose files.
+- Existing local generated-code directories and their fallback generation.
+- CI/CD workflow and registry setup.
+
+The existing local generation may continue to produce unused compatibility
+artifacts during builds. It is intentionally left in place for this migration.
+
+## Public Package Contracts
+
+### Go
+
+The Go SDK module path is:
+
+```text
+git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go
+```
+
+Generated files live at:
+
+```text
+yoresee_doc/v1/yoresee_doc.pb.go
+yoresee_doc/v1/yoresee_doc_grpc.pb.go
+```
+
+The protobuf `go_package` is changed to:
+
+```text
+git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go/yoresee_doc/v1;yoreseedocpb
+```
+
+The initial SDK release is `v0.1.0`. `backend` and `collab-go` pin this
+version instead of depending on the moving `master` branch.
+
+### Node.js
+
+The package name is `@yoresee-doc/sdk-node`, installed from:
+
+```text
+git+ssh://git@git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_node.git#v0.1.0
+```
+
+Generated output is split by runtime:
+
+```text
+esm/yoresee_doc/v1/yoresee_doc_pb.js
+esm/yoresee_doc/v1/yoresee_doc_connect.js
+cjs/yoresee_doc/v1/yoresee_doc_pb.js
+cjs/yoresee_doc/v1/yoresee_doc_grpc_pb.js
+```
+
+The package uses conditional exports and explicit `esm/*` and `cjs/*`
+subpaths. The `cjs/` directory declares CommonJS module semantics so the
+root package can remain ESM-compatible.
+
+Service import contracts are:
+
+- `frontend`: `@yoresee-doc/sdk-node/esm/yoresee_doc/v1/...`
+- `collab`: `@yoresee-doc/sdk-node/cjs/yoresee_doc/v1/...`
+
+Runtime dependencies for both generated formats are declared by the SDK:
+`@bufbuild/protobuf`, `@connectrpc/connect`, `@grpc/grpc-js`, and
+`google-protobuf`.
+
+## Generation and Repository Boundaries
+
+The generated files are committed to the SDK repositories because they are the
+published dependency artifacts. The source proto remains in the existing
+`proto` repository and is not duplicated into the SDK repositories.
+
+Generation for this initial migration is performed from the checked-out proto
+source using the existing installed toolchains. The migration does not alter
+the existing project generation scripts. Each SDK README records the source
+proto commit and the generator versions used for the artifacts.
+
+## Service Migration
+
+`backend` and `collab-go` replace local generated-package imports with the Go
+SDK import path and add the pinned Gitea module dependency. The services set
+`GOPRIVATE` in their build environment documentation where required by the
+private module.
+
+`frontend` and `collab` add the pinned Git dependency and replace aliases or
+relative paths that point to local generated files with the Node SDK exports.
+
+No service behavior or protobuf message/service definitions change.
+
+## Verification
+
+The implementation is accepted only after all of the following checks pass:
+
+- Go SDK generated package compiles and its module resolves at `v0.1.0`.
+- Node SDK can be installed from the Gitea tag and both module formats load.
+- `backend` and `collab-go` compile with the remote SDK dependency.
+- `frontend` production build resolves the ESM/Connect exports.
+- `collab` can load the CJS protobuf and gRPC exports.
+- SDK repositories have clean commits pushed to `master`, with `v0.1.0`
+  tags.
+
+## Risks and Rollback
+
+- Private Gitea dependencies require read access from developer and Docker/CI
+  environments. A failed authenticated fetch is an environment issue, not a
+  protobuf generation issue.
+- The old local generation remains redundant and may continue to fail because
+  its existing buf templates are outside this migration scope.
+- Rollback consists of reverting service dependency/import changes and the
+  protobuf `go_package` change; SDK repositories remain harmless additive
+  artifacts.