feat(acms): budget enforcement with max_file_size and max_total_size constraints #847

Closed
opened 2026-03-13 21:58:56 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit Message: feat(acms): budget enforcement with max_file_size and max_total_size constraints
  • Branch: feature/m5-budget-enforcement

Background

M5 (v3.4.0) acceptance criterion: ACMS budget enforcement must work with max_file_size and max_total_size constraints. The context assembly pipeline must respect these limits when building context views, rejecting files that exceed individual size limits and truncating or excluding content when the total budget is reached.

Per the E2E suite (m5_e2e_verification.robot line 99), the test verifies ContextView validation: zero and negative size limits are rejected, None is allowed, VALID_PHASES is correct, and invalid phases raise ValueError.

Expected Behavior

  1. max_file_size constraint prevents individual files exceeding the limit from being included
  2. max_total_size constraint caps the total context assembly output
  3. Zero and negative size limits are rejected with clear error messages
  4. None values are accepted (meaning no limit)
  5. Budget violations are reported with details on which files were excluded/truncated

Acceptance Criteria

  • max_file_size enforcement excludes oversized individual files
  • max_total_size enforcement caps total context output
  • Zero and negative size limits raise validation errors
  • None values accepted as "no limit"
  • Budget violation reports generated with details
  • Robot E2E test Context View Validation Rules passes
  • Unit tests cover: boundary conditions, mixed limits, no-limit, edge cases

Supporting Information

  • E2E test: robot/m5_e2e_verification.robot line 99
  • Related: ACMS tier management tests at line 46

Subtasks

  • Implement max_file_size enforcement in context assembly pipeline
  • Implement max_total_size enforcement in context assembly pipeline
  • Add validation for size limit values (reject zero/negative)
  • Add budget violation reporting
  • Tests (Behave): Add scenarios for budget enforcement edge cases
  • Tests (Robot): Verify E2E acceptance test passes
  • Verify coverage >=97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
## Metadata - **Commit Message**: `feat(acms): budget enforcement with max_file_size and max_total_size constraints` - **Branch**: `feature/m5-budget-enforcement` ## Background M5 (v3.4.0) acceptance criterion: ACMS budget enforcement must work with `max_file_size` and `max_total_size` constraints. The context assembly pipeline must respect these limits when building context views, rejecting files that exceed individual size limits and truncating or excluding content when the total budget is reached. Per the E2E suite (`m5_e2e_verification.robot` line 99), the test verifies ContextView validation: zero and negative size limits are rejected, None is allowed, VALID_PHASES is correct, and invalid phases raise ValueError. ## Expected Behavior 1. `max_file_size` constraint prevents individual files exceeding the limit from being included 2. `max_total_size` constraint caps the total context assembly output 3. Zero and negative size limits are rejected with clear error messages 4. None values are accepted (meaning no limit) 5. Budget violations are reported with details on which files were excluded/truncated ## Acceptance Criteria - [x] `max_file_size` enforcement excludes oversized individual files - [x] `max_total_size` enforcement caps total context output - [x] Zero and negative size limits raise validation errors - [x] None values accepted as "no limit" - [x] Budget violation reports generated with details - [x] Robot E2E test `Context View Validation Rules` passes - [x] Unit tests cover: boundary conditions, mixed limits, no-limit, edge cases ## Supporting Information - E2E test: `robot/m5_e2e_verification.robot` line 99 - Related: ACMS tier management tests at line 46 ## Subtasks - [x] Implement `max_file_size` enforcement in context assembly pipeline - [x] Implement `max_total_size` enforcement in context assembly pipeline - [x] Add validation for size limit values (reject zero/negative) - [x] Add budget violation reporting - [x] Tests (Behave): Add scenarios for budget enforcement edge cases - [x] Tests (Robot): Verify E2E acceptance test passes - [x] Verify coverage >=97% via `nox -s coverage_report` - [x] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.
freemo added this to the v3.4.0 milestone 2026-03-13 21:59:48 +00:00
Member

Implementation Notes

Design Decisions

Enforcement as a pure function: Rather than embedding byte-size logic deep inside pipeline component protocols, enforce_size_budget() was implemented as a standalone pure function in context_policy.py. This keeps the function testable in isolation, composable (callers outside the pipeline can use it), and consistent with the existing model-level design of ContextView and ProjectContextPolicy.

Pre-filter pattern: The pipeline's assemble() method applies byte-size enforcement as a pre-filter before strategy orchestration. This ensures oversized fragments are excluded before strategies rank/select them, avoiding wasted work. The token-based ContextBudget/BudgetPacker continues to handle token limits independently downstream.

Structured violation reporting: BudgetViolation records the fragment_id, human-readable reason, content_size, limit, and violation_type (max_file_size or max_total_size). BudgetEnforcementResult wraps accepted IDs + violations + cumulative size. Both are frozen Pydantic models for immutability.

Optional context_view parameter: The context_view parameter on assemble() is optional. When None, no byte-size enforcement occurs (backward compatible). When provided, enforce_size_budget() is called and results are stored on last_enforcement_result.

Key Code Locations

  • Domain models: cleveragents.domain.models.core.context_policyBudgetViolation, BudgetEnforcementResult, enforce_size_budget() (commit 3c0d839)
  • Pipeline wiring: cleveragents.application.services.acms_service.ACMSPipeline.assemble() and cleveragents.application.services.acms_pipeline.ContextAssemblyPipeline.assemble() — optional context_view pre-filter
  • Behave tests: features/m5_acms_smoke.feature — 7 new scenarios; features/steps/m5_acms_smoke_steps.py — step definitions

Pre-existing State

  • The ContextView model fields (max_file_size, max_total_size) with validators (reject zero/negative, accept None) were already implemented.
  • Enforcement at the repo indexing layer (repo_indexing_utils.walk_and_index) was already in place — this commit adds enforcement at the ACMS assembly pipeline layer.
  • The Robot E2E test Context View Validation Rules tests model-level validation only and was already passing.
  • The existing Behave smoke tests (m5_acms_smoke.feature) had model-level arithmetic checks; this commit adds scenarios exercising actual enforce_size_budget() calls and pipeline integration.

Test Results

  • nox -e lint: PASSED
  • nox -e typecheck: PASSED (0 errors)
  • nox -e unit_tests: 12,237 scenarios PASSED (461 features)
  • nox -e integration_tests: 1,672 tests PASSED
  • nox -e coverage_report: 98% (threshold: 97%)

PR

PR #1137: feature/m5-budget-enforcementmaster

## Implementation Notes ### Design Decisions **Enforcement as a pure function**: Rather than embedding byte-size logic deep inside pipeline component protocols, `enforce_size_budget()` was implemented as a standalone pure function in `context_policy.py`. This keeps the function testable in isolation, composable (callers outside the pipeline can use it), and consistent with the existing model-level design of `ContextView` and `ProjectContextPolicy`. **Pre-filter pattern**: The pipeline's `assemble()` method applies byte-size enforcement as a pre-filter *before* strategy orchestration. This ensures oversized fragments are excluded before strategies rank/select them, avoiding wasted work. The token-based `ContextBudget`/`BudgetPacker` continues to handle token limits independently downstream. **Structured violation reporting**: `BudgetViolation` records the fragment_id, human-readable reason, content_size, limit, and violation_type (`max_file_size` or `max_total_size`). `BudgetEnforcementResult` wraps accepted IDs + violations + cumulative size. Both are frozen Pydantic models for immutability. **Optional context_view parameter**: The `context_view` parameter on `assemble()` is optional. When `None`, no byte-size enforcement occurs (backward compatible). When provided, `enforce_size_budget()` is called and results are stored on `last_enforcement_result`. ### Key Code Locations - **Domain models**: `cleveragents.domain.models.core.context_policy` — `BudgetViolation`, `BudgetEnforcementResult`, `enforce_size_budget()` (commit `3c0d839`) - **Pipeline wiring**: `cleveragents.application.services.acms_service.ACMSPipeline.assemble()` and `cleveragents.application.services.acms_pipeline.ContextAssemblyPipeline.assemble()` — optional `context_view` pre-filter - **Behave tests**: `features/m5_acms_smoke.feature` — 7 new scenarios; `features/steps/m5_acms_smoke_steps.py` — step definitions ### Pre-existing State - The `ContextView` model fields (`max_file_size`, `max_total_size`) with validators (reject zero/negative, accept None) were already implemented. - Enforcement at the repo indexing layer (`repo_indexing_utils.walk_and_index`) was already in place — this commit adds enforcement at the ACMS assembly pipeline layer. - The Robot E2E test `Context View Validation Rules` tests model-level validation only and was already passing. - The existing Behave smoke tests (`m5_acms_smoke.feature`) had model-level arithmetic checks; this commit adds scenarios exercising actual `enforce_size_budget()` calls and pipeline integration. ### Test Results - **nox -e lint**: PASSED - **nox -e typecheck**: PASSED (0 errors) - **nox -e unit_tests**: 12,237 scenarios PASSED (461 features) - **nox -e integration_tests**: 1,672 tests PASSED - **nox -e coverage_report**: 98% (threshold: 97%) ### PR PR #1137: `feature/m5-budget-enforcement` → `master`
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#847
No description provided.