Bug: `ContextFragment.detail_depth` hardcoded `le=9` constraint prevents `uko-doc:` (max 10) and `uko-data:` (max 11) fragments from using their full depth range #2390

New issue

Open

opened 2026-04-03 17:30:19 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 17:30:19 +00:00

Owner

Metadata

Branch: fix/context-fragment-detail-depth-domain-max
Commit Message: fix(acms): remove hardcoded le=9 cap on ContextFragment.detail_depth to support uko-doc: and uko-data: domain max depths
Milestone: v3.4.0
Parent Epic: #396

Background

The ContextFragment model in context_fragment.py hardcodes le=9 for the detail_depth field, but the UKO ontology registry defines different maximum depths per domain (spec §41934-42331):

Domain	Max Depth	Depth Range
`uko-code:`	9	`MODULE_LISTING=0` → `FULL_SOURCE=9`
`uko-doc:`	10	`TITLE_ONLY=0` → `FULL_CONTENT=10`
`uko-data:`	11	`SCHEMA_LISTING=0` → `FULL_CATALOG=11`
`uko-infra:`	8	`SERVICE_LISTING=0` → `WITH_DEPLOYMENT=8`

Problematic code in src/cleveragents/domain/models/core/context_fragment.py:

detail_depth: int = Field(
    default=0,
    ge=0,
    le=9,  # ← hardcoded! Prevents uko-doc: (max 10) and uko-data: (max 11)
    description="Resolved integer depth: 0 (MODULE_LISTING) through 9 (FULL_SOURCE)"
)

Impact

Creating a ContextFragment for a uko-doc: resource at depth 10 (FULL_CONTENT) raises a Pydantic ValidationError — the fragment cannot be created at all.
Creating a ContextFragment for a uko-data: resource at depth 10 (WITH_SAMPLE_DATA) or 11 (FULL_CATALOG) raises a ValidationError.
The DepthReductionCompressor in acms_skeleton_compressor.py uses detail_map.max_depth to determine valid depths, but fragments cannot be created at those depths due to the hardcoded constraint.
The field description is also incorrect — it says "0 (MODULE_LISTING) through 9 (FULL_SOURCE)" which is only true for uko-code: domain fragments.

Affected Code Locations

src/cleveragents/domain/models/core/context_fragment.py line ~80 (detail_depth field definition)
src/cleveragents/domain/models/acms/ontology_registry.py lines ~100-160 (domain max_depth definitions — authoritative per spec §41934-42331)
src/cleveragents/application/services/acms_skeleton_compressor.py (DepthReductionCompressor uses detail_map.max_depth)

Expected Behavior (per spec §41934-42331)

ContextFragment.detail_depth should accept values up to the maximum depth of the fragment's UKO domain. The Pydantic constraint should either be:

Removed from the model field and validated at the service layer using the domain's DetailLevelMap.max_depth, or
Raised to the global maximum (11, for uko-data:) with a note that domain-specific upper bounds are enforced by the service layer.

The field description must also be corrected to be domain-agnostic (e.g., "Resolved integer depth level for the fragment's UKO domain; valid range is 0 through the domain's max_depth").

Actual Behavior

ContextFragment.detail_depth is capped at 9 regardless of domain, causing ValidationError for valid uko-doc: depth 10 and uko-data: depths 10–11 fragments.

Subtasks

Audit ContextFragment.detail_depth field in context_fragment.py and determine the correct fix strategy (remove le= constraint vs. raise to global max of 11)
Update detail_depth field: remove or correct the le= constraint and fix the field description to be domain-agnostic
Add/update domain-level depth validation in the service layer (or confirm DetailLevelMap.max_depth is already enforced) so out-of-range depths are still caught at the appropriate boundary
Update Behave unit test scenarios in features/ to cover uko-doc: depth 10 and uko-data: depths 10–11 fragment creation (previously untestable due to the constraint)
Update Behave unit test scenarios to assert that depths exceeding a domain's max_depth are rejected at the service layer
Verify DepthReductionCompressor in acms_skeleton_compressor.py correctly handles the full depth range for all four UKO domains
Run nox -e typecheck and confirm no regressions
Run nox -e unit_tests and confirm all scenarios pass
Run nox -e coverage_report and confirm coverage ≥ 97%

Definition of Done

ContextFragment.detail_depth accepts depth values up to the domain's max_depth (10 for uko-doc:, 11 for uko-data:) without raising a ValidationError
The field description accurately reflects the domain-agnostic depth range
Domain-specific upper-bound validation is enforced at the correct architectural layer (service layer, not model layer)
Behave scenarios cover all four UKO domain depth ranges including previously-blocked depths
DepthReductionCompressor correctly operates across the full depth range for all domains
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/context-fragment-detail-depth-domain-max` - **Commit Message**: `fix(acms): remove hardcoded le=9 cap on ContextFragment.detail_depth to support uko-doc: and uko-data: domain max depths` - **Milestone**: v3.4.0 - **Parent Epic**: #396 ## Background The `ContextFragment` model in `context_fragment.py` hardcodes `le=9` for the `detail_depth` field, but the UKO ontology registry defines different maximum depths per domain (spec §41934-42331): | Domain | Max Depth | Depth Range | |---|---|---| | `uko-code:` | 9 | `MODULE_LISTING=0` → `FULL_SOURCE=9` | | `uko-doc:` | 10 | `TITLE_ONLY=0` → `FULL_CONTENT=10` | | `uko-data:` | 11 | `SCHEMA_LISTING=0` → `FULL_CATALOG=11` | | `uko-infra:` | 8 | `SERVICE_LISTING=0` → `WITH_DEPLOYMENT=8` | **Problematic code** in `src/cleveragents/domain/models/core/context_fragment.py`: ```python detail_depth: int = Field( default=0, ge=0, le=9, # ← hardcoded! Prevents uko-doc: (max 10) and uko-data: (max 11) description="Resolved integer depth: 0 (MODULE_LISTING) through 9 (FULL_SOURCE)" ) ``` ## Impact 1. Creating a `ContextFragment` for a `uko-doc:` resource at depth 10 (`FULL_CONTENT`) raises a Pydantic `ValidationError` — the fragment cannot be created at all. 2. Creating a `ContextFragment` for a `uko-data:` resource at depth 10 (`WITH_SAMPLE_DATA`) or 11 (`FULL_CATALOG`) raises a `ValidationError`. 3. The `DepthReductionCompressor` in `acms_skeleton_compressor.py` uses `detail_map.max_depth` to determine valid depths, but fragments cannot be created at those depths due to the hardcoded constraint. 4. The field description is also incorrect — it says "0 (MODULE_LISTING) through 9 (FULL_SOURCE)" which is only true for `uko-code:` domain fragments. ## Affected Code Locations - `src/cleveragents/domain/models/core/context_fragment.py` line ~80 (`detail_depth` field definition) - `src/cleveragents/domain/models/acms/ontology_registry.py` lines ~100-160 (domain `max_depth` definitions — authoritative per spec §41934-42331) - `src/cleveragents/application/services/acms_skeleton_compressor.py` (`DepthReductionCompressor` uses `detail_map.max_depth`) ## Expected Behavior (per spec §41934-42331) `ContextFragment.detail_depth` should accept values up to the maximum depth of the fragment's UKO domain. The Pydantic constraint should either be: - **Removed** from the model field and validated at the service layer using the domain's `DetailLevelMap.max_depth`, or - **Raised** to the global maximum (11, for `uko-data:`) with a note that domain-specific upper bounds are enforced by the service layer. The field description must also be corrected to be domain-agnostic (e.g., "Resolved integer depth level for the fragment's UKO domain; valid range is 0 through the domain's max_depth"). ## Actual Behavior `ContextFragment.detail_depth` is capped at 9 regardless of domain, causing `ValidationError` for valid `uko-doc:` depth 10 and `uko-data:` depths 10–11 fragments. ## Subtasks - [ ] Audit `ContextFragment.detail_depth` field in `context_fragment.py` and determine the correct fix strategy (remove `le=` constraint vs. raise to global max of 11) - [ ] Update `detail_depth` field: remove or correct the `le=` constraint and fix the field description to be domain-agnostic - [ ] Add/update domain-level depth validation in the service layer (or confirm `DetailLevelMap.max_depth` is already enforced) so out-of-range depths are still caught at the appropriate boundary - [ ] Update Behave unit test scenarios in `features/` to cover `uko-doc:` depth 10 and `uko-data:` depths 10–11 fragment creation (previously untestable due to the constraint) - [ ] Update Behave unit test scenarios to assert that depths exceeding a domain's `max_depth` are rejected at the service layer - [ ] Verify `DepthReductionCompressor` in `acms_skeleton_compressor.py` correctly handles the full depth range for all four UKO domains - [ ] Run `nox -e typecheck` and confirm no regressions - [ ] Run `nox -e unit_tests` and confirm all scenarios pass - [ ] Run `nox -e coverage_report` and confirm coverage ≥ 97% ## Definition of Done - [ ] `ContextFragment.detail_depth` accepts depth values up to the domain's `max_depth` (10 for `uko-doc:`, 11 for `uko-data:`) without raising a `ValidationError` - [ ] The field description accurately reflects the domain-agnostic depth range - [ ] Domain-specific upper-bound validation is enforced at the correct architectural layer (service layer, not model layer) - [ ] Behave scenarios cover all four UKO domain depth ranges including previously-blocked depths - [ ] `DepthReductionCompressor` correctly operates across the full depth range for all domains - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.4.0 milestone

2026-04-03 17:30:24 +00:00

freemo added a new dependency

2026-04-03 17:31:16 +00:00

#396 Epic: ACMS Context Pipeline

freemo referenced this issue

2026-04-03 17:35:12 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.6.0 — Session Tracker #2360

freemo referenced this issue

2026-04-03 17:35:14 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.6.0 — Session Tracker #2360

freemo commented

2026-04-03 18:23:14 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High — The hardcoded le=9 constraint on detail_depth prevents uko-doc: (max 10) and uko-data: (max 11) fragments from using their full depth range as defined in the UKO ontology.
Milestone: v3.4.0 (as specified in issue metadata)
MoSCoW: Should Have — While this limits the depth range for specific UKO domains, most fragments work within the 0-9 range. This should be fixed for spec compliance but is not blocking core functionality.
Parent Epic: #396 (ACMS Context Pipeline)

Well-described with clear spec references and UKO ontology analysis. Valid and actionable.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: High — The hardcoded `le=9` constraint on `detail_depth` prevents `uko-doc:` (max 10) and `uko-data:` (max 11) fragments from using their full depth range as defined in the UKO ontology. - **Milestone**: v3.4.0 (as specified in issue metadata) - **MoSCoW**: Should Have — While this limits the depth range for specific UKO domains, most fragments work within the 0-9 range. This should be fixed for spec compliance but is not blocking core functionality. - **Parent Epic**: #396 (ACMS Context Pipeline) Well-described with clear spec references and UKO ontology analysis. Valid and actionable. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner