[Graphite MQ] Draft PR GROUP:spec_0228e5 (PRs 3901, 3902)

[graphite-app]

This draft PR was created by the Graphite merge queue.
Trunk will be fast forwarded to the HEAD of this PR when CI passes, and the original PRs will be closed.

The following PRs are included in this draft PR:

• #3901
• #3902

[railway-app]

This PR was not deployed automatically as @graphite-app[bot] does not have access to the Railway project.

In order to get automatic PR deploys, please add @graphite-app[bot] to your workspace on Railway.

[claude]

PR Review: Documentation and Schema Generation

This PR merges two changes:

• PR doc: document version upgrades #3901: Document version upgrades
• PR doc: auto-generate docs for engine config and registry config #3902: Auto-generate documentation for engine and registry configurations

✅ Strengths

Schema Generation Infrastructure

• Well-designed build-time schema generation for both Rust (engine config) and TypeScript (actor/registry configs)
• Proper use of schemars for Rust and zod with JSON Schema conversion for TypeScript
• Good separation between runtime schemas and documentation schemas (e.g., DocActorConfigSchema vs ActorConfigSchema)
• Schemas are checked into version control at engine/artifacts/ and rivetkit-typescript/artifacts/, making them discoverable

Documentation Quality

• Comprehensive new documentation pages with clear examples
• Interactive schema viewers in the documentation site
• Good use of code groups to show different configuration methods
• Helpful cross-references between related documentation pages

Build System Integration

• Proper Turbo.json configuration with dependency tracking
• Clean separation of concerns between schema generation scripts

🔍 Issues & Recommendations

1. Error Handling in build.rs (Medium Priority)

File: engine/packages/config-schema-gen/build.rs:7-18

The build script uses multiple .unwrap() calls which will cause cryptic build failures. Use .expect() with descriptive messages instead for better error diagnostics.

2. Hardcoded Path Traversal (Low Priority)

File: engine/packages/config-schema-gen/build.rs:8-16

The build script assumes a specific directory structure with exactly 3 levels of parents. This is fragile if the package is moved. Consider using CARGO_WORKSPACE_DIR or searching upward for Cargo.toml to find the workspace root dynamically.

3. Missing Package in Build Member (Critical)

File: Cargo.toml

I notice that config-schema-gen is created but not listed in the workspace members. This means it wont be built during normal cargo build operations. Verify that engine/packages/config-schema-gen is in the workspace members list. If its intentionally excluded, add a comment explaining why.

4. Schema Duplication (Low Priority)

Files:

• rivetkit-json-schema/registry-config.json
• rivetkit-typescript/artifacts/registry-config.json

Both files appear to contain the same registry config schema. This could lead to drift if one is updated but not the other. Clarify if both are needed and document their relationship, or consolidate to a single source.

5. Documentation Typos (Low Priority)

File: website/src/content/docs/actors/versions.mdx:41

• Missing "the" - should be "New actors go to the new version"

File: website/src/content/docs/general/registry-configuration.mdx:95

• Missing space before dash in cross-reference link

6. Package Renaming Follow-through (Medium Priority)

Files:

• Cargo.toml:17 - changes dump-openapi to api-public-openapi-gen
• Cargo.toml:378-379 - workspace dependency renamed

The renaming is good for clarity, but verify that all references are updated across the codebase, CI/CD scripts dont reference the old name, and documentation doesnt reference dump-openapi.

🎯 Summary

Overall Assessment: This is a solid infrastructure improvement that will make documentation maintenance much easier. The schema generation is well-architected and the documentation is comprehensive.

Must Fix Before Merge:

• Issue [SVC-2504] Fix 5 GB upload limit for local development from Cloudflare #3: Verify config-schema-gen is in workspace members (or document why its excluded)

Should Fix:

• Issue [SVC-2555] Set up issue templates #1: Improve error messages in build.rs
• Issue [SVC-2358] Enable Redis memory overcommit #5: Fix documentation typos
• Issue Remove servers not in salt #6: Verify all dump-openapi references are updated

Nice to Have:

• Issue [SVC-2479] Send cluster events to PostHog #2: Make path traversal more robust
• Issue [SVC-2483] Remove hardcoded uses of rivet.gg #4: Clarify schema duplication purpose

📝 Code Quality Score: 8/10

The implementation is clean and well-structured. The main areas for improvement are around error handling robustness and minor documentation polish.

---

Review generated by Claude Code