Private
Public Access
conductor(campaign): metadata_ssdl_defusing_20260624 - 3-child SSDL defusing campaign
Campaign: address the parent code_path_audit_20260607 Finding 1 (CRITICAL)
Metadata 4.01e22 effective codepaths via 3 SSDL techniques.
3 children, sequential, with budget gates:
1. metadata_nil_sentinel_20260624 (>= 10% drop): introduce
NIL_METADATA sentinel + migrate 6 nil-check functions.
2. metadata_generational_handle_20260624 (>= 20% drop,
BLOCKED_BY 1): wrap Metadata in (index, generation) handle;
collapse lifetime branches to 1 lookup + 1 cmp.
3. metadata_field_cache_20260624 (>= 30% drop, BLOCKED_BY 2):
MetadataFieldCache keyed by (handle.index, field_name);
123 string-keyed entry.get('key', default) sites become
cache lookups.
Each child has its own spec/plan/metadata/state. Budget gate
after each child: re-measure effective codepaths; if drop < threshold,
PAUSE the campaign and report to user.
End-of-campaign TRACK_COMPLETION captures the cumulative reduction
vs the 4.01e22 baseline. Deferred follow-up: apply the same
3 SSDL primitives to the 4 other dict[str, Any] aliases
(FileItem, CommsLogEntry, HistoryMessage, ToolDefinition, ToolCall).
16 files committed: 4 directories x 4 files each (spec, plan,
metadata, state).
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
{
|
||||
"track_id": "metadata_field_cache_20260624",
|
||||
"name": "Child 3: Metadata Field Cache",
|
||||
"track_type": "campaign_child",
|
||||
"parent_campaign": "metadata_ssdl_defusing_20260624",
|
||||
"created_date": "2026-06-24",
|
||||
"branch": "master",
|
||||
"depends_on": ["code_path_audit_20260607", "metadata_nil_sentinel_20260624", "metadata_generational_handle_20260624"],
|
||||
"blocks_within_campaign": [],
|
||||
"scope": {
|
||||
"new_files": [
|
||||
"conductor/tracks/metadata_field_cache_20260624/spec.md",
|
||||
"conductor/tracks/metadata_field_cache_20260624/plan.md",
|
||||
"conductor/tracks/metadata_field_cache_20260624/metadata.json",
|
||||
"conductor/tracks/metadata_field_cache_20260624/state.toml",
|
||||
"tests/test_metadata_field_cache.py",
|
||||
"docs/reports/TRACK_COMPLETION_metadata_field_cache_20260624.md"
|
||||
],
|
||||
"modified_files": [
|
||||
"src/aggregate.py (MetadataFieldCache + field-access migrations)",
|
||||
"src/ai_client.py (field-access migrations; specific files TBD by Tier 2)",
|
||||
"conductor/tracks.md",
|
||||
"docs/reports/campaign_measurements_20260624.md"
|
||||
],
|
||||
"deleted_files": []
|
||||
},
|
||||
"estimated_effort": {
|
||||
"method": "scope (per workflow.md §Tier 1 Track Initialization Rules). NO day estimates.",
|
||||
"phase_1": "1 task: 4 behavioral tests",
|
||||
"phase_2": "1 task: MetadataFieldCache + 123 field-access site migrations",
|
||||
"phase_3": "1 task: 6 VCs + budget gate + TRACK_COMPLETION + state + tracks.md + campaign SHIPPED"
|
||||
},
|
||||
"verification_criteria": [
|
||||
"VC1: MetadataFieldCache exists",
|
||||
"VC2: Production code uses the cache at field-access sites",
|
||||
"VC3: Behavioral test exists and passes",
|
||||
"VC4: Budget gate met (drop >= 30% vs post-child-2 measurement)",
|
||||
"VC5: Full test suite remains green (11/11 tiers PASS)",
|
||||
"VC6: 4 audit gates remain clean"
|
||||
],
|
||||
"known_issues": [],
|
||||
"deferred_to_followup_tracks": [],
|
||||
"regressions_and_pre_existing_failures": [],
|
||||
"pre_existing_failures_remaining": [],
|
||||
"risk_register": [
|
||||
{
|
||||
"id": "risk-1",
|
||||
"description": "Cache invalidation is wrong (stale values returned)",
|
||||
"likelihood": "medium",
|
||||
"impact": "Production code returns stale Metadata values",
|
||||
"mitigation": "Cache keyed by handle; when underlying value changes, handle's generation bumps (via registry), invalidating cache entries"
|
||||
},
|
||||
{
|
||||
"id": "risk-2",
|
||||
"description": "The 123 field-access sites are not actually 123 (audit was wrong)",
|
||||
"likelihood": "low",
|
||||
"impact": "Migration scope unclear; budget gate measurement is invalid",
|
||||
"mitigation": "Re-run detect_access_pattern_evidence after migration to count actual sites"
|
||||
},
|
||||
{
|
||||
"id": "risk-3",
|
||||
"description": "Budget gate fails (drop < 30%)",
|
||||
"likelihood": "low",
|
||||
"impact": "Child 3 cannot ship; campaign pauses",
|
||||
"mitigation": "Cache collapses 123 lookups to 1 lookup each; expected large drop"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,86 @@
|
||||
# Plan: metadata_field_cache_20260624
|
||||
|
||||
3 tasks, 3 atomic commits. Same pattern as children 1 and 2.
|
||||
|
||||
## Phase 1: Behavioral Test (1 task)
|
||||
|
||||
- [ ] Task 1.1: Write `tests/test_metadata_field_cache.py`.
|
||||
- WHERE: New file `tests/test_metadata_field_cache.py`
|
||||
- WHAT: 4 tests (per spec FR3)
|
||||
- HOW: Use 1-space indentation
|
||||
- SAFETY: Test imports `MetadataFieldCache` + `MetadataHandle` from their production locations
|
||||
- COMMIT: `test(metadata): behavioral test for field cache (MetadataFieldCache)`
|
||||
- GIT NOTE: 4 tests; will be RED until Phase 2 ships
|
||||
- VERIFY: `uv run pytest tests/test_metadata_field_cache.py -v` shows 4/4 FAIL (expected)
|
||||
|
||||
## Phase 2: Implementation (1 task)
|
||||
|
||||
- [ ] Task 2.1: Add `MetadataFieldCache` + migrate the 123 field-access sites.
|
||||
- WHERE: `src/aggregate.py` (cache type) + the 123 field-access sites across `src/`
|
||||
- WHAT:
|
||||
- Add `class MetadataFieldCache` with `get`, `set`, `invalidate` methods
|
||||
- Migrate the 123 `entry.get('key', default)` and `entry['key']` sites to use the cache
|
||||
- HOW: Use `manual-slop_py_add_def` for the cache type; `manual-slop_edit_file` for the migration sites
|
||||
- SAFETY: Verify with `ast.parse`; run the 4 tests + the child-1 + child-2 tests + the 14 previously-failing tests
|
||||
- COMMIT: `feat(metadata): MetadataFieldCache + 123 field-access site migrations`
|
||||
- GIT NOTE: 123 sites now use cache; cache invalidation on generation bump (child 2's registry)
|
||||
- VERIFY: `uv run pytest tests/test_metadata_field_cache.py tests/test_metadata_generational_handle.py tests/test_metadata_nil_sentinel.py -v` shows all PASS
|
||||
|
||||
## Phase 3: Verification + Budget Gate (1 task)
|
||||
|
||||
- [ ] Task 3.1: Run all 6 VCs; capture the budget gate measurement; write end-of-campaign TRACK_COMPLETION.
|
||||
- WHERE: All audit gates + test suite + SSDL measurement + campaign umbrella
|
||||
- WHAT:
|
||||
- Run VC1-VC6 for the child
|
||||
- Compute the new effective-codepaths number
|
||||
- Compare to post-child-2 measurement; require drop ≥ 30%
|
||||
- Write the child's TRACK_COMPLETION report
|
||||
- Update this track's `state.toml` to `status = "completed"`, all 3 phases completed
|
||||
- Append to campaign_measurements_20260624.md
|
||||
- Update conductor/tracks.md
|
||||
- ALSO: write the campaign's end-of-campaign TRACK_COMPLETION at `docs/reports/TRACK_COMPLETION_metadata_ssdl_defusing_20260624.md`
|
||||
- Update the campaign umbrella's `state.toml` to `status = "completed"`, all 4 phases completed
|
||||
- HOW: Run each VC command, capture output, write the report.
|
||||
- SAFETY: Same as children 1 and 2
|
||||
- COMMIT: 3 child commits (state, TRACK_COMPLETION, tracks.md) + 3 campaign commits (state, TRACK_COMPLETION, tracks.md)
|
||||
- GIT NOTE: Per workflow.md
|
||||
- VERIFY: All 6 VCs pass; budget gate met; campaign umbrella SHIPPED
|
||||
|
||||
## Commit Log (Expected)
|
||||
|
||||
1. `test(metadata): behavioral test for field cache` (Task 1.1)
|
||||
2. `feat(metadata): MetadataFieldCache + 123 field-access site migrations` (Task 2.1)
|
||||
3. `conductor(state): metadata_field_cache_20260624 SHIPPED` (Task 3.1)
|
||||
4. `docs(reports): TRACK_COMPLETION for metadata_field_cache_20260624` (Task 3.1)
|
||||
5. `conductor(tracks): add metadata_field_cache_20260624 row` (Task 3.1)
|
||||
6. `docs(reports): TRACK_COMPLETION for metadata_ssdl_defusing_20260624` (Task 3.1)
|
||||
7. `conductor(state): metadata_ssdl_defusing_20260624 SHIPPED` (Task 3.1)
|
||||
8. `conductor(tracks): add metadata_ssdl_defusing_20260624 row + 3 child rows` (Task 3.1)
|
||||
|
||||
## Verification Commands
|
||||
|
||||
```bash
|
||||
# VC1: cache type exists
|
||||
grep -rn "class MetadataFieldCache" src/
|
||||
|
||||
# VC2: production uses cache
|
||||
grep -rn "field_cache.get\|field_cache.set" src/
|
||||
|
||||
# VC3: tests pass
|
||||
uv run pytest tests/test_metadata_field_cache.py -v
|
||||
|
||||
# VC4: budget gate (final measurement)
|
||||
uv run python -c "from src.code_path_audit_ssdl import compute_effective_codepaths; ...; print(compute_effective_codepaths(metadata_profile, 'src'))"
|
||||
|
||||
# VC5: full test suite
|
||||
uv run python scripts/run_tests_batched.py
|
||||
|
||||
# VC6: 4 audit gates
|
||||
uv run python scripts/audit_weak_types.py --strict
|
||||
uv run python scripts/generate_type_registry.py --check
|
||||
uv run python scripts/audit_main_thread_imports.py
|
||||
uv run python scripts/audit_no_models_config_io.py
|
||||
|
||||
# Campaign-wide
|
||||
cat docs/reports/TRACK_COMPLETION_metadata_ssdl_defusing_20260624.md
|
||||
```
|
||||
@@ -0,0 +1,114 @@
|
||||
# Track Specification: metadata_field_cache_20260624
|
||||
|
||||
## Overview
|
||||
|
||||
Child 3 of the `metadata_ssdl_defusing_20260624` campaign. Introduces `MetadataFieldCache` keyed by `(handle.index, field_name)`. The 123 string-keyed `entry.get('key', default)` field-access sites become 123 cache lookups. **BLOCKED_BY child 2** (the handle provides the stable cache key).
|
||||
|
||||
## Current State Audit (master @ child-2-SHIPPED, after metadata_generational_handle_20260624)
|
||||
|
||||
- `NIL_METADATA` sentinel exists (from child 1)
|
||||
- `MetadataHandle` + `MetadataHandleRegistry` exist (from child 2)
|
||||
- The 123 field-access sites in `src/aggregate.py`, `src/ai_client.py`, and other production files use `entry.get('key', default)` or `entry['key']` patterns
|
||||
|
||||
## Goals
|
||||
|
||||
| ID | Goal | Acceptance |
|
||||
|---|---|---|
|
||||
| G1 | `MetadataFieldCache` introduced: keyed by `(handle.index, field_name)` | The cache type is exported; can be created, queried, and invalidated |
|
||||
| G2 | The 123 field-access sites use the cache | `grep -rn "MetadataFieldCache\|field_cache.get\|field_cache.set" src/` returns ≥ 1 hit per site |
|
||||
| G3 | 1 behavioral test for the cache | `tests/test_metadata_field_cache.py` exists; asserts hit, miss, invalidation via generation bump |
|
||||
| G4 | Budget gate met: effective-codepaths drop ≥ 30% vs post-child-2 measurement | Re-measurement shows the drop |
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Touching the 4 other `dict[str, Any]` aliases — out of scope
|
||||
- Touching the list-typed aggregates — out of scope
|
||||
- Replacing the 3 candidate placeholders — blocked on `any_type_componentization_20260621`
|
||||
- Cache for the inner Metadata values within nested structures (the campaign handles the top-level Metadata)
|
||||
- Eviction policy (LRU, etc.) — the cache is small (123 entries) and keyed by handle; no eviction needed
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### FR1: Cache type
|
||||
|
||||
In a sensible location (likely `src/aggregate.py`):
|
||||
|
||||
```python
|
||||
class MetadataFieldCache:
|
||||
def __init__(self) -> None:
|
||||
self._cache: dict[tuple[int, str], Any] = {}
|
||||
self._generations: dict[int, int] = {} # mirrors the registry
|
||||
|
||||
def get(self, handle: MetadataHandle, field_name: str) -> Any:
|
||||
# if handle.generation != self._generations[handle.index], return None (sentinel equivalent)
|
||||
# otherwise return self._cache.get((handle.index, field_name), NIL)
|
||||
|
||||
def set(self, handle: MetadataHandle, field_name: str, value: Any) -> None:
|
||||
# if handle.generation != self._generations[handle.index], ignore (stale write)
|
||||
# otherwise self._cache[(handle.index, field_name)] = value
|
||||
|
||||
def invalidate(self, index: int) -> None:
|
||||
# clear all entries for this index; bump generation
|
||||
```
|
||||
|
||||
(Exact API up to Tier 2; the contract is: cache keyed by `(index, field_name)`, generation-aware invalidation.)
|
||||
|
||||
### FR2: Migrate the 123 field-access sites
|
||||
|
||||
For each `entry.get('key', default)` or `entry['key']` site in the production code:
|
||||
- Replace with `cache.get(handle, 'key') or NIL_METADATA.get('key', default)` (or similar; the exact pattern depends on whether the cache returns the raw value or the cached Metadata)
|
||||
- Alternative: the cache stores the entire Metadata (or per-field values), and consumers request `(handle, 'field_name')`
|
||||
|
||||
The exact migration pattern is up to Tier 2. The acceptance criterion is that the 123 sites are migrated.
|
||||
|
||||
### FR3: Behavioral test
|
||||
|
||||
`tests/test_metadata_field_cache.py` with at least 4 tests:
|
||||
- `test_cache_hit`: `cache.get(handle, 'key')` after `cache.set(handle, 'key', value)` returns value
|
||||
- `test_cache_miss`: `cache.get(handle, 'key')` without prior set returns NIL (or None)
|
||||
- `test_cache_invalidation_on_bump`: after `cache.invalidate(handle.index)`, `cache.get(handle, 'key')` returns NIL
|
||||
- `test_cache_stale_write_ignored`: `cache.set(stale_handle, 'key', value)` does not write
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
- NFR1: 1-space indentation
|
||||
- NFR2: CRLF line endings on Windows
|
||||
- NFR3: No comments in source code
|
||||
- NFR4: Per-task atomic commits with git notes
|
||||
- NFR5: No new pip dependencies
|
||||
- NFR6: `Result[T]` returns for fallible cache methods
|
||||
- NFR7: No new `src/<thing>.py` files
|
||||
|
||||
## Architecture Reference
|
||||
|
||||
- `NIL_METADATA` (child 1) — the sentinel returned by `cache.get` on miss or stale write
|
||||
- `MetadataHandle` + `MetadataHandleRegistry` (child 2) — the handle provides the cache key
|
||||
- `docs/reports/code_path_audit/2026-06-22/AUDIT_REPORT.md` Finding 1 Fix 2 — the Immediate-Mode Cache proposal
|
||||
- `src/code_path_audit_ssdl.py` — the SSDL infrastructure used to measure progress
|
||||
- `conductor/code_styleguides/data_oriented_design.md` — canonical DOD reference
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- The 4 other `dict[str, Any]` aliases (deferred)
|
||||
- The 3 candidate placeholders (blocked)
|
||||
- Runtime profiling (Track F)
|
||||
- Eviction policy (the cache is small)
|
||||
|
||||
## Verification Criteria (Definition of Done)
|
||||
|
||||
| # | Criterion | Verification command |
|
||||
|---|---|---|
|
||||
| VC1 | `MetadataFieldCache` exists | `grep -rn "class MetadataFieldCache" src/` |
|
||||
| VC2 | Production code uses the cache at field-access sites | `grep -rn "field_cache.get\|field_cache.set" src/` returns ≥ 1 hit |
|
||||
| VC3 | Behavioral test exists and passes | `uv run pytest tests/test_metadata_field_cache.py -v` |
|
||||
| VC4 | Budget gate met | `compute_effective_codepaths(Metadata_profile)` returns number ≥ 30% smaller than post-child-2 measurement |
|
||||
| VC5 | Full test suite remains green | `uv run python scripts/run_tests_batched.py` → 11/11 tiers PASS |
|
||||
| VC6 | 4 audit gates remain clean | weak_types ≤ 112, type_registry in sync, main_thread_imports clean, no_models_config_io clean |
|
||||
|
||||
## Risks
|
||||
|
||||
| # | Risk | Likelihood | Mitigation |
|
||||
|---|---|---|---|
|
||||
| R1 | Cache invalidation is wrong (stale values returned) | medium | Cache is keyed by handle; when the underlying value changes, the handle's generation bumps (via the registry), invalidating cache entries. Behavioral test verifies the invalidation path. |
|
||||
| R2 | The 123 field-access sites are not actually 123 (audit was wrong) | low | Re-run `src.code_path_audit.detect_access_pattern_evidence` after migration to count the actual sites |
|
||||
| R3 | Budget gate fails (drop < 30%) | low | The cache collapses 123 lookups to 1 lookup each; expected to be a large drop. If not, investigate. |
|
||||
@@ -0,0 +1,44 @@
|
||||
# Track state for metadata_field_cache_20260624
|
||||
# Child 3 of metadata_ssdl_defusing_20260624 campaign.
|
||||
# 3 phases, 3 tasks. BLOCKED_BY children 1 and 2.
|
||||
|
||||
[meta]
|
||||
track_id = "metadata_field_cache_20260624"
|
||||
name = "Child 3: Metadata Field Cache"
|
||||
status = "active"
|
||||
current_phase = 0
|
||||
last_updated = "2026-06-24"
|
||||
|
||||
[parent]
|
||||
parent_campaign = "metadata_ssdl_defusing_20260624"
|
||||
|
||||
[blocked_by]
|
||||
code_path_audit_20260607 = "shipped"
|
||||
metadata_nil_sentinel_20260624 = "shipped"
|
||||
metadata_generational_handle_20260624 = "shipped"
|
||||
|
||||
[blocks]
|
||||
# This child blocks nothing within the campaign (it's the last child)
|
||||
|
||||
[phases]
|
||||
phase_1 = { status = "pending", checkpointsha = "", name = "Behavioral Test" }
|
||||
phase_2 = { status = "pending", checkpointsha = "", name = "Implementation (Cache + 123 migrations)" }
|
||||
phase_3 = { status = "pending", checkpointsha = "", name = "Verification + Budget Gate + Campaign SHIPPED" }
|
||||
|
||||
[tasks]
|
||||
t1_1 = { status = "pending", commit_sha = "", description = "Write tests/test_metadata_field_cache.py with 4 tests (red)" }
|
||||
t2_1 = { status = "pending", commit_sha = "", description = "Add MetadataFieldCache + migrate 123 field-access sites" }
|
||||
t3_1 = { status = "pending", commit_sha = "", description = "Run all 6 VCs; capture budget gate; write child TRACK_COMPLETION; write campaign TRACK_COMPLETION; update both state.toml + tracks.md" }
|
||||
|
||||
[verification]
|
||||
vc1_field_cache_exists = false
|
||||
vc2_production_uses_cache = false
|
||||
vc3_behavioral_test_passes = false
|
||||
vc4_budget_gate_met = false
|
||||
vc5_full_test_suite_green = false
|
||||
vc6_audit_gates_clean = false
|
||||
|
||||
[budget_gate]
|
||||
baseline = "post_child_2_measurement"
|
||||
expected_drop_pct = 30
|
||||
post_child_3_measurement = null
|
||||
Reference in New Issue
Block a user