feat(governor): P2-1 v2 schema with group/action + backward compat

[heidi-dang]

Summary

P2-1: Policy model v2 + schema compatibility

• Add GovVersion enum (V1/V2)
• Add ViolationAction enum (NONE/WARN/SOFT_KILL/HARD_KILL)
• Add group field (max 32 chars) for group policy attach
• Add action field for violation ladder
• Add cpu.period_us and mem.high_bytes for v2 cgroup features
• Add TimeoutPolicy with apply_deadline_ms
• New ACK codes: NACK_INVALID_GROUP, NACK_GROUP_CAPACITY
• Backward compatible: v1 messages parse unchanged

Tests

• 5 new v2 parser tests (pass 25/25 total)
• All existing tests pass

Pass criteria

• CI green all platforms
• governance PASS

[gemini-code-assist]

Summary of Changes

Hello @heidi-dang, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant upgrade to the governor's policy model, moving from V1 to V2. It enhances policy management by enabling group-level assignments and defining explicit actions for policy violations. The update also integrates modern cgroup V2 parameters for CPU and memory control and introduces a timeout mechanism for policy application, all while preserving compatibility with existing V1 policies.

Highlights

• Policy Model V2 Introduction: Introduced a V2 policy model with GovVersion enum to distinguish between policy versions.
• Violation Action Enum: Added ViolationAction enum (NONE, WARN, SOFT_KILL, HARD_KILL) to define explicit responses to policy violations.
• Group-Based Policy Application: Enabled group-based policy application by adding a new group field to GovApplyMsg, supporting group IDs up to 32 characters.
• Cgroup V2 Features: Incorporated cgroup V2 features by adding cpu.period_us to CpuPolicy and mem.high_bytes to MemPolicy.
• Timeout Policy: Implemented TimeoutPolicy with apply_deadline_ms for deadline-based policy application.
• New ACK Codes: Expanded AckCode with NACK_INVALID_GROUP and NACK_GROUP_CAPACITY for new error conditions related to group policies.
• Backward Compatibility: Ensured backward compatibility, allowing V1 messages to be parsed unchanged.
• New V2 Parser Tests: Added 5 new parser tests specifically for V2 features, bringing the total to 25 passing tests.
• Existing Test Pass: Confirmed that all existing tests continue to pass, ensuring no regressions were introduced.

Changelog

• include/heidi-kernel/gov_rule.h
  • Defined kMaxGroupIdLen constant for group ID length validation.
  • Added GovVersion and ViolationAction enums.
  • Extended AckCode enum with NACK_INVALID_GROUP and NACK_GROUP_CAPACITY.
  • Updated CpuPolicy with period_us and MemPolicy with high_bytes.
  • Introduced TimeoutPolicy struct with apply_deadline_ms.
  • Modified GovApplyMsg to include version, group, action, and timeouts fields.
  • Changed ApplyField enum base type to uint16_t and added new fields for V2 features.
• src/governor/gov_rule.cpp
  • Updated ack_to_string function to recognize new AckCode values.
  • Modified parse_gov_apply to handle parsing of version, group, action, cpu.period_us, and mem.high_bytes fields.
  • Added validation logic for the group field's maximum length during parsing.
• tests/test_gov_rule.cpp
  • Added new test cases for ack_to_string with the new AckCode values.
  • Introduced dedicated tests for parsing V2 messages, covering group, action, cpu.period_us, and mem.high_bytes.
  • Included a test to verify backward compatibility for V1 policy messages.

Activity

• New V2 parser tests were added and passed, ensuring the new features function as expected.
• All existing tests were run and passed, confirming no regressions were introduced.
• Continuous Integration (CI) passed on all platforms.
• Governance checks passed.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces the P2-1 v2 schema, enhancing the governor's policy model with new features such as group/action fields, CPU period, memory high bytes, and timeout policies. No specific security vulnerabilities were identified. The changes maintain backward compatibility for v1 messages, are well-tested with new parser tests, and updates to gov_rule.h and gov_rule.cpp are consistent, including the correct upgrade of the ApplyField enum to uint16_t. Overall, the implementation is robust and aligns with the pull request's objectives.