If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tokio-rs/prost shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 24+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tokio-rs/prost repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tokio-rs/prost.

What it runs against: a local clone of tokio-rs/prost — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tokio-rs/prost | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 42 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tokio-rs/prost. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tokio-rs/prost.git
#   cd prost
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tokio-rs/prost and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tokio-rs/prost(\\.git)?\\b" \\
  && ok "origin remote is tokio-rs/prost" \\
  || miss "origin remote is not tokio-rs/prost (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "prost/src/lib.rs" \\
  && ok "prost/src/lib.rs" \\
  || miss "missing critical file: prost/src/lib.rs"
test -f "prost-build/src/code_generator.rs" \\
  && ok "prost-build/src/code_generator.rs" \\
  || miss "missing critical file: prost-build/src/code_generator.rs"
test -f "prost-derive/src/lib.rs" \\
  && ok "prost-derive/src/lib.rs" \\
  || miss "missing critical file: prost-derive/src/lib.rs"
test -f "prost-build/src/ast.rs" \\
  && ok "prost-build/src/ast.rs" \\
  || miss "missing critical file: prost-build/src/ast.rs"
test -f "prost-build/src/lib.rs" \\
  && ok "prost-build/src/lib.rs" \\
  || miss "missing critical file: prost-build/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 42 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~12d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tokio-rs/prost"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PROST is a Protocol Buffers (protobuf) compiler and code generator for Rust that transforms .proto files into idiomatic Rust types with serialization/deserialization support. It generates simple, readable Rust code from proto2 and proto3 syntax while preserving proto comments, respecting package namespaces, and using the bytes crate's Buf/BufMut abstractions instead of std::io. Monorepo structure with 11 workspace members: core prost/ (runtime serialization), prost-build/ (proto compiler invocation), prost-derive/ (procedural macros for attributes), prost-types/ (well-known types), plus test/bench suites split by Rust edition (2015/2018/2024) and features (no-std, fuzz, conformance). Build-time code generation happens via prost-build consuming build.rs files; runtime uses generated #[derive(...)] structs.

Rust developers and systems engineers who need to serialize/deserialize protobuf messages in Rust projects—particularly those building microservices, gRPC applications, or cross-language systems where protobuf is the wire format. Contributors tend to be Tokio ecosystem maintainers and Rust protocol buffer enthusiasts.

Production-ready and stable: the repo shows passively-maintained status with continuous CI (GitHub Actions workflow in .github/workflows/ci.yml), v0.14.3 released, MSRV pinned to Rust 1.82, and comprehensive test suites across 8+ test crates (tests, tests-2015, tests-2018, tests-2024, tests-no-std, conformance). Last activity visible in workspace versioning and CI workflows indicates active maintenance by Tokio team.

Low-to-moderate risk: the codebase is 652KB of Rust with strong testing (conformance tests, fuzzing infrastructure in /fuzz with AFL and cargo-fuzz, Kani formal verification in KANI.md), but marked as 'passively-maintained' meaning slower response cycles. Dependency risk is mitigated by the Tokio project's maintenance model; no single-maintainer bottleneck evident. Breaking changes are tracked in CHANGELOG.md, and protoc is now required as a system dependency (v0.11+), which adds external tooling risk.

The repo is in maintenance mode with passive updates. Recent signals: workspace version bumped to 0.14.3, MSRV updated to Rust 1.82, protoc made mandatory (breaking change in v0.11), and conformance testing expanded (conformance/ crate with failing_tests.txt tracking proto3 compliance). Fuzzing infrastructure (fuzz/, FUZZING.md) and formal verification (KANI.md) are active quality gates.

git clone https://github.com/tokio-rs/prost.git
cd prost
cargo build
cargo test

You'll need protoc installed separately; see https://protobuf.dev/ for your OS. Run cargo test --all to verify the 8+ test suites.

Daily commands: No server to run—this is a code generator. To test code generation: cargo build -p prost-build && cargo test -p prost. To benchmark: cargo bench --manifest-path benchmarks/Cargo.toml. To run conformance tests: cargo test --manifest-path conformance/Cargo.toml.

• prost/src/lib.rs — Core library entry point defining the Message trait and core serialization/deserialization APIs that all protobuf messages implement.
• prost-build/src/code_generator.rs — Main code generation engine that transforms proto file ASTs into idiomatic Rust code; must understand to add language features.
• prost-derive/src/lib.rs — Procedural macro definitions for #[derive(Message)] and related derives that power the code generation pipeline.
• prost-build/src/ast.rs — Abstract syntax tree definitions for parsed .proto files; fundamental data structure threaded through the entire build system.
• prost-build/src/lib.rs — Build-time API exposing Config and compilation entry points; the primary interface for users integrating prost into build.rs.
• prost-types/Cargo.toml — Well-known types package that provides standard protobuf types (Timestamp, Duration, Any, etc.) widely used in proto definitions.
• Cargo.toml — Workspace root defining all member crates, shared dependencies, and minimum MSRV (1.82) that constrain implementation choices.

Add Support for a New Protobuf Scalar Type

1. Add type variant to AST enum in prost-build/src/ast.rs (e.g., MyType variant) (prost-build/src/ast.rs)
2. Implement encoding/decoding in prost/src/encoding/ for wire format serialization (prost/src/encoding/mod.rs)
3. Update code_generator.rs to emit correct Rust type and encoding calls for the new scalar (prost-build/src/code_generator.rs)
4. Add derive macro logic in prost-derive/src/field/scalar.rs to handle Encode/Decode (prost-derive/src/field/scalar.rs)
5. Add golden test fixture in prost-build/src/fixtures/ with .proto file and expected output (prost-build/src/fixtures/smoke_test/smoke_test.proto)

Add a Custom Code Generation Option (like prost attributes)

1. Define configuration option in prost-build/src/config.rs (e.g., pub fn my_option) (prost-build/src/config.rs)
2. Parse the option in prost-build/src/code_generator.rs where attributes are processed (prost-build/src/code_generator.rs)
3. Conditionally emit different Rust code based on the option in code_generator.rs or field modules (prost-build/src/code_generator/syntax.rs)
4. Add test fixture and golden file in prost-build/src/fixtures/ to validate output (prost-build/src/fixtures/field_attributes/_expected_field_attributes.rs)

Support a New Message Composition Pattern (e.g., Oneof improvements)

1. Extend oneof handling in prost-build/src/ast.rs to capture new semantic information (prost-build/src/ast.rs)
2. Update code generation logic in prost-build/src/code_generator.rs to emit new Rust patterns (prost-build/src/code_generator.rs)
3. Implement Encode/Decode logic for new pattern in prost-derive/src/field/oneof.rs (prost-derive/src/field/oneof.rs)
4. Add fixture proto file and expected output to validate via integration test (prost-build/src/fixtures/smoke_test/smoke_test.proto)

• Procedural Macros (prost-derive) — Enable idiomatic Rust #[derive(Message)] syntax; moves boilerplate code generation from build-time to compile-time, reducing runtime overhead.
• Separate prost vs prost-build crates — Allows runtime library (prost) to be lightweight and no_std compatible; build-time concerns (protobuf parsing) isolated to prost-build, reducing transitive deps in shipped binaries.
• Workspace monorepo (Cargo workspaces) — Enables unified versioning, shared CI/CD, and easy coordination across derive macros, code generators, and runtime without divergent version skew.
• Well-known types in prost-types — Provides google.protobuf standard types (Timestamp, Duration, Any, etc.) pre-generated and optimized; avoids duplicating code across projects.
• Rust 1.82 MSRV — Leverages recent Rust features (e.g., 2021 edition, reliable derive macros) while maintaining broad compatibility; tested in CI.

• Code generation at build-time rather than runtime reflection

  • Why: Enables static type safety, zero-cost abstractions, and idiomatic Rust patterns; avoids runtime marshalling overhead.
  • Consequence: Requires a build step (prost-build) during compilation; not suitable for dynamic proto schemas loaded at runtime.

• Manual Message trait implementation vs auto-trait magic

  • Why: Derive macros make code transparent and debuggable; users see generated code via expand tools.
  • Consequence: Slightly more verbose proc-macro code; but clear ownership semantics and type checking.

• No gRPC in prost core (separate ecosystem)

  • Why: Keeps prost focused on serialization; gRPC layered on top (tonic) following Unix philosophy.
  • Consequence: Users must explicitly add tonic or similar for RPC; enables interoperability with other RPC frameworks.

• Strict protobuf conformance testing

  • Why: Ensures compatibility with standard protobuf tooling and other language implementations.
  • Consequence: High maintenance burden; must track Protocol Buffers spec changes; test suite (conformance/) may fail on bleeding-edge protobuf versions.

Required external dependency: protoc binary (v3.5+) must be installed separately and on $PATH; build will fail without it (changed in v0.11). No-std caveat: tests-no-std/ crate is included but not all features support it—check feature flags. Edition complexity: test crates split across Rust editions (2015/2018/2024); running all tests requires cargo test --workspace not just single-crate test. Conformance gaps: conformance/failing_tests.txt lists known unimplemented proto3 features; do not assume full parity. Macro limits: prost-derive uses syn/quote and may have issues with deeply nested proto messages.

• Protocol Buffers (protobuf) wire format — Understanding varint encoding, zigzag encoding for signed ints, and length-delimited groups is essential to debug serialization issues and contribute to prost/src/encoding.rs
• Procedural macros (syn/quote) — PROST uses prost-derive (procedural macros) to generate impl Message and serialization code; must understand how to modify code generation logic
• Buf and BufMut traits (bytes crate) — Core abstraction for zero-copy reading/writing in serialization; replacing std::io::Read/Write throughout PROST's encoding layer
• Proto2 vs Proto3 syntax differences — PROST generates different code for proto2 and proto3 (e.g., presence tracking, packed encoding); conformance/failing_tests.txt tracks proto3-specific gaps
• AST (Abstract Syntax Tree) parsing and transformation — prost-build/src/ast.rs parses proto syntax and emits Rust code; understanding AST traversal is key to modifying code generation
• Cargo workspaces and build.rs (build scripts) — PROST uses 11 workspace members and build.rs to invoke protoc at compile time; understanding Cargo's build pipeline is essential for extending the toolchain
• Fuzzing with AFL and cargo-fuzz — PROST's fuzz/ directory contains fuzz harnesses for finding parser/encoder edge cases; understanding fuzzing methodology helps validate correctness

• tokio-rs/tokio — Parent organization and async runtime that powers many gRPC use cases built on PROST
• hyperium/tonic — gRPC framework for Rust that uses PROST for protobuf serialization; reference consumer
• stepancheg/rust-protobuf — Alternative protobuf implementation for Rust with different design (mutable message builders); direct competitor
• tokio-rs/bytes — Dependency providing Buf/BufMut abstractions used throughout PROST's encoding layer
• dtolnay/prost-reflect — Third-party extension adding runtime reflection on top of PROST (not included in core)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add conformance test coverage for proto2 syntax features

The conformance/tests/conformance.rs exists but conformance/failing_tests.txt suggests known gaps. Proto2-specific features (required fields, extensions, groups) lack dedicated conformance tests. This would improve spec compliance and catch regressions.

• [ ] Review conformance/failing_tests.txt to identify proto2-specific gaps
• [ ] Create new proto2 test cases in conformance/tests/ focusing on required field validation, extensions, and group encoding
• [ ] Add corresponding .proto fixtures in conformance/src/ for proto2 syntax
• [ ] Update CI workflow in .github/workflows/ci.yml to run conformance tests if not already included
• [ ] Document which proto2 features are covered in conformance/README.md (create if missing)

Add fuzzing targets for prost-build code generation

fuzz/fuzzers/ contains proto3.rs and proto2.rs for deserialization, but prost-build's code generation logic (prost-build/src/code_generator.rs) lacks fuzzing coverage. This could catch code generation bugs, panic conditions, or security issues in build-time processing.

• [ ] Create fuzz/fuzzers/code_generator.rs targeting prost_build::ast and prost_build::code_generator modules
• [ ] Use fuzzing to generate random proto definitions and test code_generator output for validity
• [ ] Ensure fuzzer handles syntax.rs and c_escaping.rs edge cases (special characters in identifiers, escape sequences)
• [ ] Integrate fuzzing target into CI via .github/workflows/cifuzz.yml
• [ ] Document in FUZZING.md with example invocation

Add compile-time tests for Rust edition compatibility (2015/2018/2024)

The workspace includes tests-2015, tests-2018, and tests-2024 subdirectories but there's no CI matrix testing generated code against all three editions. This ensures prost-derive output is compatible across editions as MSRV=1.82 targets modern Rust.

• [ ] Review tests-2015/, tests-2018/, tests-2024/ to identify which tests run per edition
• [ ] Add a matrix job in .github/workflows/ci.yml that runs tests separately for edition = 2015, 2018, 2021 (or 2024)
• [ ] Ensure prost-derive/src/ generates edition-compatible code by testing #![edition] directives in generated code
• [ ] Add a script (e.g., prepare-release.sh pattern) to validate that all editions compile without warnings
• [ ] Document expected edition support in README.md or prost-derive/README.md

• Add missing wire format encoding tests: prost/src/ likely lacks exhaustive tests for varint edge cases (max u64, negative i64 in proto2). Pick a specific encoding variant and add property-based tests using proptest.
• Expand conformance test coverage: conformance/failing_tests.txt tracks unimplemented proto3 features (e.g., JSON mapping, arena allocation semantics). Pick one feature, implement it in prost-build/src/ast.rs, and add test vectors.
• Document prost-build API: prost-build/README.md exists but lacks concrete examples for custom code generation (e.g., generating custom derives, custom message types). Add 2-3 worked examples in prost-build/examples/.

The PROST protocol buffer library demonstrates reasonable security practices with active fuzzing, conformance testing, and dependabot integration. However, the 'passively-maintained' status is a concern for timely security updates. The codebase shows no obvious hardcoded secrets, injection vulnerabilities, or exposed credentials based on file structure analysis. The main risks are: (1) limited active maintenance affecting response time to vulnerabilities, (2) known conformance test failures that should be security-reviewed, and (3) build-time code execution risks. The library appears suitable for general use but requires active dependency monitoring by consumers, particularly for security-critical applications.

• Medium · Passively Maintained Project — README.md. The project is marked as 'passively-maintained' in its README, indicating limited active security updates and maintenance. This could result in delayed patching of security vulnerabilities discovered in dependencies or the project itself. Fix: Establish a regular security audit schedule. Monitor dependencies using tools like 'cargo audit' and 'dependabot' (already configured). Consider increased caution when using this library in security-critical applications.
• Low · Fuzzing Infrastructure Present — fuzz/ directory. While fuzzing is a positive security practice, the presence of fuzz targets and AFL fuzzing infrastructure suggests the project is actively looking for edge cases and potential crashes. This is healthy but also indicates areas that may have been problematic. Fix: Continue fuzzing efforts. Ensure fuzzing results are regularly reviewed and regressions are tracked. Document any discovered issues.
• Low · Multiple Test Suites with Different Configurations — tests/, tests-2015/, tests-2018/, tests-2024/, tests-no-std/. The presence of multiple test suites (tests-2015, tests-2018, tests-2024, tests-no-std) suggests potential for inconsistent security behavior across different Rust editions and configurations. The tests-no-std variant is particularly important as no-std environments may have different security implications. Fix: Ensure all test suites, particularly tests-no-std, receive equivalent security-focused testing. Document any known differences in security posture across editions.
• Low · Conformance Testing with Known Failing Tests — conformance/failing_tests.txt. The presence of 'conformance/failing_tests.txt' indicates known protocol buffer conformance issues. While this may be expected, it could indicate edge cases where protocol parsing may behave unexpectedly. Fix: Review the failing tests to understand if any relate to security-critical parsing paths. Document why these tests fail and whether they pose security risks.
• Low · Build Script Dependencies — benchmarks/build.rs and other build.rs files. The project uses build.rs scripts (e.g., in benchmarks/) which execute arbitrary code during compilation. This is a potential supply chain attack vector if dependencies are compromised. Fix: Minimize build script functionality. Pin and review all transitive build dependencies. Consider using workspace-level dependency management for build scripts.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.