Generating clients

When to use thisCopy Anchor Link

• You work in Rust, Java, C#, Ruby or another language with no official SDK. Rust and Java are coming soon.
• You want Python or TypeScript messages without checking in the repository's generated stubs.
• You are building a provider or a tool that reads Numinance messages, and you want your own build to own the generated code.

PrerequisitesCopy Anchor Link

• A clone of https://github.com/dsha256/numinance-spec.git.
• The buf CLI (this page ran 1.46.0), or protoc for your target language.
• A generator plugin for your target language.

What the repository gives youCopy Anchor Link

buf.yaml declares one module rooted at proto:

version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
    - COMMENTS
breaking:
  use:
    - FILE
  ignore_unstable_packages: true

The packages under proto/numinance/ are annotations, events, evidence, kinds, plugin, ports and types. Every port is a separate package (authorexecutor, ciexecutor, evidencestore, knowledge, sandboxprovider, scm, ticketing, transparencylog, verifier), so you generate only the ones you implement.

The checked-in buf.gen.yaml is the maintainers' generation recipe for the Go, Python, TypeScript and JSON Schema outputs. Its own comments say it runs through a just gen task, with Go generators pinned in a tools module and a Python generator taken from grpcio-tools. Those inputs are not in the public checkout, so copy the idea, not the file. It does state two useful facts: no generator is remote, and the JSON Schemas for the configuration kinds are produced from numinance.kinds.v1 only.

Run itCopy Anchor Link

All commands are run from the root of the checkout.

buf build -o /dev/null

buf lint

version: v2
plugins:
  - protoc_builtin: python
    out: gen-py

buf generate --template buf.gen.demo.yaml

buf build: exit 0
buf lint: exit 0, no findings
buf generate: exit 0, 44 files written under gen-py

A plain protoc -I proto --python_out=OUT proto/numinance/types/v1/types.proto proto/numinance/annotations/v1/annotations.proto with protoc 29.3 also wrote types_pb2.py and annotations_pb2.py.

What is and is not testedCopy Anchor Link

You can use the conformance kits' vectors as a behavioral reference, and the evidence conformance vectors are language neutral because they are directories of files. A client in another language is correct only to the extent you test it against them.

Failure modes and safeguardsCopy Anchor Link

• A schema is stricter than the type. Protobuf types do not carry the bounds, ordering and uniqueness rules written in comments and annotations. The host rejects over-limit input rather than truncating it, so a generated client that builds an oversized message gets a refusal, not a silent fix.
• Descriptor mismatch. A plugin ships a descriptor set, and the host's compiled copy of each port file is authoritative. A differing shared port file fails install.
• Generator drift. Different generator versions produce different code. Pin yours.
• Untagged contract. The packages are v1, but the repository is not tagged yet; read versioning before you build on a field.

Next stepsCopy Anchor Link