alvis/oO

Files

alvis bd3ea1b8b1 docs(schema): update docs for #54 — proto registry + buf CI gate

- packages/shared-types/README.md: new — documents HTTP vs event surfaces,
  proto file layout, schema evolution rules, and how to run buf locally
- ml/serving/README.md: note pydantic payload validation in consumer section
- CLAUDE.md: replace "schema registry enforced when #54 lands" with
  the actual state; remove #54 from active-work list

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-25 16:53:20 +00:00

events

feat(schema): protobuf event registry + buf CI gate (#54 )

2026-04-25 16:48:24 +00:00

src

feat(schema): protobuf event registry + buf CI gate (#54 )

2026-04-25 16:48:24 +00:00

.gitkeep

chore: scaffold oO monorepo with architecture, roadmap, and module stubs

2026-04-13 14:19:56 +00:00

package.json

feat(schema): protobuf event registry + buf CI gate (#54 )

2026-04-25 16:48:24 +00:00

README.md

docs(schema): update docs for #54 — proto registry + buf CI gate

2026-04-25 16:53:20 +00:00

tsconfig.json

feat: Phase 0 walking skeleton — monorepo, API, web, ML stub

2026-04-14 12:41:24 +00:00

vitest.config.ts

feat: ε-greedy v1 as active policy; dwell-time reward inference; offline sim framework

2026-04-16 07:44:37 +00:00

README.md

@oo/shared-types

Canonical contracts for all inter-module communication. Two surfaces:

Surface	Format	Location
HTTP (sync)	OpenAPI / TypeScript interfaces	`src/http/`
Events (async)	Protocol Buffers + TS interfaces	`src/events/`, `events/`

HTTP types

Hand-written TypeScript interfaces generated from OpenAPI specs. Imported by services/api, apps/web, and ml/serving (Python hand-mirrors).

File	Types
`src/http/tip.ts`	`TipCandidate`, `RecommendResponse`, `TipFeedback`
`src/http/auth.ts`	`SessionUser`
`src/http/integrations.ts`	`IntegrationsResponse`, `Integration`
`src/http/user.ts`	`UserProfile`
`src/http/signal.ts`	`Signal`, `SignalSource`

Event types

Protobuf schemas live in events/oo/events/v1/. TypeScript interfaces in src/events/index.ts mirror the proto envelope and payload types.

Proto file	Messages
`envelope.proto`	`Envelope` (wraps every event)
`signals.proto`	`TaskSyncedPayload`, `TipServedPayload`, `TipFeedbackPayload`, `TipRewardFailedPayload`
`integration.proto`	`IntegrationTokenExpiredPayload`

Schema evolution rules (ADR-0005):

Additive changes only within a version (new fields, new message types).
Removed fields must be marked reserved — never reuse a field number.
Breaking changes require a new package version (oo.events.v2) and a schemaVersion bump in the envelope.

Schema registry / CI gate

buf enforces lint and breaking-change detection on every PR that touches events/:

# Lint
buf lint events/

# Breaking-change check against main
buf breaking events/ --against '.git#branch=main,subdir=packages/shared-types/events'

Local shortcut: ./scripts/buf-check.sh

CI: .gitea/workflows/buf-check.yaml (requires a Gitea Actions runner).

Install buf: curl -sSfL https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64 -o /usr/local/bin/buf && chmod +x /usr/local/bin/buf

Contract

/health — not applicable (library package, no process).

Extraction criteria — always a shared library. Extract to a separate registry service only when schema governance requires independent versioning and deployment (e.g. external consumers, SLA divergence from the monorepo).