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

- Add proto schemas in packages/shared-types/events/ (oo.events.v1):
  envelope.proto, signals.proto, integration.proto
- buf.yaml with STANDARD lint + FILE breaking-change rules
- .gitea/workflows/buf-check.yaml: lint + breaking check on every PR
  touching events/ (needs a Gitea Actions runner to execute)
- scripts/buf-check.sh: local equivalent of the CI check
- NormalizedEvent TS envelope gains eventId, schemaVersion, producer
  to align with the proto Envelope message
- ml/serving/schemas.py: pydantic models mirroring the v1 proto types
- nats_consumer.py: validate payloads via pydantic instead of raw .get()

A field-rename PR will now fail buf breaking with exit code 100 and
show the offending messages. To make a breaking change: keep the old
field reserved, add the new one, bump schema_version to v2.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-04-25 16:48:24 +00:00
parent f48b5a7646
commit d539fde0c1
10 changed files with 213 additions and 13 deletions

View File

@@ -1,6 +1,6 @@
/**
* NormalizedEvent — the durable envelope for all events flowing through
* the system. Today: in-process EventEmitter. Tomorrow: NATS JetStream.
* the system. Mirrors oo.events.v1.Envelope in packages/shared-types/events/.
*
* Subject taxonomy:
* signals.task.synced — Todoist (or other source) task list refreshed
@@ -10,10 +10,16 @@
* signals.integration.token_expired — OAuth token needs reconnect
*/
export interface NormalizedEvent<T = unknown> {
/** UUID assigned by bus on publish */
eventId: string;
/** NATS-style subject: domain.entity.verb */
subject: string;
/** ISO 8601 timestamp */
ts: string;
occurredAt: string;
/** "v1" — bump for breaking payload changes; see packages/shared-types/events/ */
schemaVersion: 'v1';
/** e.g. "services/api" */
producer: string;
/** Monotonically increasing sequence number (in-process ring; JetStream seq in prod) */
seq: number;
payload: T;