ibexharness
DocsBlogReleasesRoadmap
GitHub
ibexharness

Documentation

Architecture Decision RecordsADR-0002: Repository foundation bootstrapADR-0003: Branch protection and merge policyADR-0004: Protobuf and code generation policyADR-0005: Postgres migration strategyADR-0006: Auth protobuf contract (`ibex.auth.v1`)ADR-0007: Auth token validation implementationADR-0008: Security scanning and CI quality gatesADR-0009: Permission bitmap layoutADR-0010: Cryptography policyADR-0011: Proxy auth gRPC client and middlewareADR-0012: Proxy request normalization (OpenAI chat)ADR-0013: Proxy input validation and stable error envelopeADR-0014: Core domain migration sequencingADR-0015: Proxy rate limit skeleton (Phase 1)ADR-0016: Proxy agent identity verification (Phase 1)ADR-0017: Request ID and trace context strategy (Phase 1)ADR-0018: Graceful shutdown contract (Phase 1)ADR-0019: OpenTelemetry provider configuration (Phase 1)ADR-0020: Shared package boundaries — `packages/config` and `packages/apierror`ADR-0021: Prometheus Metric Catalog (Phase 1)ADR-0022: Health check contract (Phase 1)ADR-0023: Docs site architecture (Phase 1.5)
ADRs›ADR-0004: Protobuf and code generation policy
ADRs

ADR-0004: Protobuf and code generation policy

Architecture decision record 0004.

ADR-0004: Protobuf and code generation policy

  • Status: Accepted
  • Date: 2026-05-30
  • Authors: IBEX Harness team

Context

IBEX Harness uses protobuf as the internal contract source of truth (FILE_STRUCTURE.md §4.1). The first contract is ContextAssemblyService in ibex.context.v1, defined in API_DOCUMENTATION.md. We need consistent linting, breaking-change detection, and a clear policy for generated code before services consume protos.

Decision

1) Buf toolchain

  • Lint: buf lint with STANDARD rules in packages/proto.

  • Breaking: buf breaking with FILE breaking rules against main:

    bash
    buf breaking --against "https://github.com/Rick1330/ibex-harness.git#branch=main,subdir=packages/proto"

  • CI: Optional buf-lint job runs lint + breaking on pull requests (not a branch-protection required check until explicitly promoted).

2) Generated code — do not commit gen/

  • packages/proto/gen/ is gitignored and not produced in CI.
  • Developers run buf generate locally when implementing a service that consumes protos.
  • Rationale: No Go/Python/TS consumers exist yet; avoids noisy diffs and stale generated stubs. Revisit when the first service imports generated types (likely services/proxy or services/context).

3) Versioning and compatibility

  • Package path: ibex.<domain>.v1 (e.g. ibex.context.v1).
  • Field numbers: Never reuse; reserve removed fields with reserved.
  • Additive changes only within v1: new optional fields, new RPCs (with care).
  • Breaking changes (rename, type change, required field, RPC removal): new package version (v2) or new service; align with API_DOCUMENTATION.md API versioning policy.
  • go_package: Set on protos for tooling; canonical Go module path finalized when root go.mod is added.

Consequences

Positive

  • Contracts are reviewable, linted, and protected from accidental breaking edits.
  • Clear handoff to service implementation PRs.

Negative

  • Consumers must run buf generate locally until CI generation is adopted.
  • First proto PR establishes baseline; all future changes must pass buf breaking.

References

  • packages/proto/README.md
  • API_DOCUMENTATION.md — gRPC proto definition
  • ADR-0002

Was this page helpful?

Edit on GitHub

Last updated on

PreviousADR-0003: Branch protection and merge policyNextADR-0005: Postgres migration strategy

On this page

  • Context
  • Decision
  • 1) Buf toolchain
  • 2) Generated code — do not commit gen/
  • 3) Versioning and compatibility
  • Consequences
  • Positive
  • Negative
  • References
0%