aim2be protobuf tree

Status: L-1 substrate-prep authoring. Authored 2026-05-14 per .planning/23-stage-b-proto-contracts.md. Files compile against buf v1.x + protoc-gen-go / protoc-gen-java / protoc-gen-grpc-java / protoc-gen-ts / grpc_tools.protoc.

Stage B target: every cross-service contract (Centrifugo channel envelope + proxy callback gRPC services + intra-cluster service-to-service gRPC) lives here. Per-service codegen lands in _gen/ (gitignored).

Layout

protobuf/
├── README.md                     # this file
├── buf.yaml                       # buf module config + lint rules
├── buf.gen.yaml                   # codegen targets (Java + TS + Python)
├── realtime/
│   └── v1/
│       ├── envelope.proto         # Tag-based event envelope (Centrifugo channel payload)
│       ├── connect.proto          # connect_proxy.Validate
│       ├── subscribe.proto        # subscribe_proxy.Authorize
│       ├── publish.proto          # publish_proxy.Validate
│       └── rpc.proto              # rpc_proxy.Route
└── shared/
    └── v1/
        └── ids.proto              # strong-typed UUID wrapper messages

Future additions (post-L0):

• identity/v1/ — identity-service gRPC + Avro events
• family/v1/, diary/v1/, calendar/v1/, notification/v1/, chatbot/v1/ — per-service gRPC + events
• observability/v1/error_event.proto — structured error event schema per ADR-0013

Versioning

• realtime/v1/*.proto frozen at Stage B L7 close.
• Minor version bumps (add optional field) allowed; require backward-compat.
• Major version bumps (remove or renumber field) require 90-day deprecation window + new realtime/v2/ directory.

buf-lint + buf-breaking

CI is wired in .forgejo/workflows/buf-lint.yml (runner label aim2be-rework). Three jobs run on every push to main and every pull-request targeting main:

• buf lint — STANDARD + COMMENTS rules (configured in buf.yaml).
• buf build -o /dev/null — validates the whole module compiles.
• scripts/check-import-direction.sh — mechanical guard forbidding realtime/v1/*.proto from importing family/v1/... or user/v1/.... See buf.yaml for the rationale (producer-owned realtime/v1 must stay a leaf of the import graph; reverse coupling is a layering violation).

buf breaking --against '.git#tag=release/v1.0' will be added after the L7 release tag lands.

Manual contract test for the import-direction guard:

# Add a forbidden import temporarily:
printf '\nimport "family/v1/family_context.proto";\n' >> realtime/v1/connect.proto
./scripts/check-import-direction.sh  # exit code 1 + finding printed
git checkout -- realtime/v1/connect.proto
./scripts/check-import-direction.sh  # exit code 0

Codegen

buf generate emits to _gen/ (gitignored):

• Java: _gen/java/com/aim2be/... — vendored into each Java service via Maven system scope or local Nexus.
• TypeScript: _gen/ts/ — published as @aim2be/protobuf local npm package for PWA + Capacitor.
• Python: _gen/python/ — published as aim2be-protobuf wheel for chatbot-service.

buf and protoc invocations live in CI; local dev uses buf mod update + buf generate.

Authority

This directory is the canonical source of truth for every Stage B contract. Per .planning/23-stage-b-proto-contracts.md:

Single shared proto tree, vendored into each consuming service via the standard buf/grpc-tooling pipeline.

NOT in any submodule. Centralization is deliberate — schema evolution requires a single PR review surface.