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).

conductor/tracks/metadata_generational_handle_20260624/metadata.json

@@ -0,0 +1,68 @@
+{
+  "track_id": "metadata_generational_handle_20260624",
+  "name": "Child 2: Metadata Generational Handle",
+  "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"],
+  "blocks_within_campaign": ["metadata_field_cache_20260624"],
+  "scope": {
+    "new_files": [
+      "conductor/tracks/metadata_generational_handle_20260624/spec.md",
+      "conductor/tracks/metadata_generational_handle_20260624/plan.md",
+      "conductor/tracks/metadata_generational_handle_20260624/metadata.json",
+      "conductor/tracks/metadata_generational_handle_20260624/state.toml",
+      "tests/test_metadata_generational_handle.py",
+      "docs/reports/TRACK_COMPLETION_metadata_generational_handle_20260624.md"
+    ],
+    "modified_files": [
+      "src/aggregate.py (MetadataHandle + Registry types + lifetime-check migrations)",
+      "src/ai_client.py (lifetime-check 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: MetadataHandle + Registry + lifetime-check migrations",
+    "phase_3": "1 task: 6 VCs + budget gate + TRACK_COMPLETION + state + tracks.md"
+  },
+  "verification_criteria": [
+    "VC1: MetadataHandle + MetadataHandleRegistry exist",
+    "VC2: Production code uses handle + registry at entry points",
+    "VC3: Behavioral test exists and passes",
+    "VC4: Budget gate met (drop >= 20% vs post-child-1 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": "The handle breaks code that expects raw Metadata",
+      "likelihood": "medium",
+      "impact": "Production code that does entry['key'] directly fails",
+      "mitigation": "Handle is a wrapper; consumers can extract raw value via .value; behavioral test verifies backwards-compat"
+    },
+    {
+      "id": "risk-2",
+      "description": "The registry's lookup is not actually O(1)",
+      "likelihood": "low",
+      "impact": "Cache pattern in child 3 doesn't work as expected",
+      "mitigation": "Registry uses dict[int, int]; lookup is O(1) by construction"
+    },
+    {
+      "id": "risk-3",
+      "description": "Budget gate fails (drop < 20%)",
+      "likelihood": "low",
+      "impact": "Child 2 cannot ship; campaign pauses",
+      "mitigation": "3466 branch points include lifetime checks; replacing with handle lookup should drop the count"
+    }
+  ]
+}

conductor/tracks/metadata_generational_handle_20260624/plan.md

@@ -0,0 +1,79 @@
+# Plan: metadata_generational_handle_20260624
+
+3 tasks, 3 atomic commits. Same pattern as child 1.
+
+## Phase 1: Behavioral Test (1 task)
+
+- [ ] Task 1.1: Write `tests/test_metadata_generational_handle.py`.
+  - WHERE: New file `tests/test_metadata_generational_handle.py`
+  - WHAT: 4 tests (per spec FR3)
+  - HOW: Use 1-space indentation
+  - SAFETY: Test imports `MetadataHandle` and `MetadataHandleRegistry` from their production location
+  - COMMIT: `test(metadata): behavioral test for generational handle (MetadataHandle + Registry)`
+  - GIT NOTE: 4 tests; will be RED until Phase 2 ships
+  - VERIFY: `uv run pytest tests/test_metadata_generational_handle.py -v` shows 4/4 FAIL (expected)
+
+## Phase 2: Implementation (1 task)
+
+- [ ] Task 2.1: Add `MetadataHandle` + `MetadataHandleRegistry` + migrate lifetime-check code.
+  - WHERE: `src/aggregate.py` (or another existing module; no new `src/<thing>.py` files)
+  - WHAT:
+    - Add `@dataclass(frozen=True) class MetadataHandle` with `index: int` and `generation: int`
+    - Add `class MetadataHandleRegistry` with `register`, `lookup`, `bump_generation` methods
+    - Migrate lifetime-check sites in `src/aggregate.py`, `src/ai_client.py`, and any other production files
+  - HOW: Use `manual-slop_py_add_def` for the new types; `manual-slop_edit_file` for the migration sites
+  - SAFETY: Verify with `ast.parse`; run the 4 tests + the child-1 tests + the 14 previously-failing tests
+  - COMMIT: `feat(metadata): MetadataHandle + Registry + lifetime-check migrations`
+  - GIT NOTE: Lifetime checks now go through registry.lookup; generation mismatch returns NIL_METADATA from child 1
+  - VERIFY: `uv run pytest 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.
+  - WHERE: All audit gates + test suite + SSDL measurement
+  - WHAT:
+    - Run VC1-VC6
+    - Compute the new effective-codepaths number
+    - Compare to post-child-1 measurement; require drop ≥ 20%
+    - Write TRACK_COMPLETION report
+    - Update state.toml to `status = "completed"`, all 3 phases completed
+    - Append to campaign_measurements_20260624.md
+    - Update conductor/tracks.md
+  - HOW: Same as child 1 phase 3
+  - SAFETY: Same as child 1
+  - COMMIT: 3 commits (state, TRACK_COMPLETION, tracks.md)
+  - GIT NOTE: Per workflow.md
+  - VERIFY: All 6 VCs pass; budget gate met; campaign unblocked for child 3
+
+## Commit Log (Expected)
+
+1. `test(metadata): behavioral test for generational handle` (Task 1.1)
+2. `feat(metadata): MetadataHandle + Registry + lifetime-check migrations` (Task 2.1)
+3. `conductor(state): metadata_generational_handle_20260624 SHIPPED` (Task 3.1)
+4. `docs(reports): TRACK_COMPLETION for metadata_generational_handle_20260624` (Task 3.1)
+5. `conductor(tracks): add metadata_generational_handle_20260624 row` (Task 3.1)
+
+## Verification Commands
+
+```bash
+# VC1: types exist
+grep -rn "class MetadataHandle\|class MetadataHandleRegistry" src/
+
+# VC2: production uses handle
+grep -rn "registry.lookup\|registry.register" src/
+
+# VC3: tests pass
+uv run pytest tests/test_metadata_generational_handle.py -v
+
+# VC4: budget gate
+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
+```

conductor/tracks/metadata_generational_handle_20260624/spec.md

@@ -0,0 +1,115 @@
+# Track Specification: metadata_generational_handle_20260624
+
+## Overview
+
+Child 2 of the `metadata_ssdl_defusing_20260624` campaign. Wraps `Metadata` in a `(index, generation)` handle resolved through a registry. Collapses lifetime branches to 1 lookup + 1 generation comparison. **BLOCKED_BY child 1** (the nil sentinel is the fallback path on generation mismatch).
+
+## Current State Audit (master @ child-1-SHIPPED, after metadata_nil_sentinel_20260624)
+
+- `NIL_METADATA` sentinel exists (from child 1)
+- The 6 nil-check functions use sentinel-return
+- The 3466 branch points in the parent audit include lifetime checks (e.g., "is this handle still valid?")
+- `src/aggregate.py` and `src/ai_client.py` contain lifetime checks; they should be replaced with handle lookup + generation comparison
+
+## Goals
+
+| ID | Goal | Acceptance |
+|---|---|---|
+| G1 | `MetadataHandle` (or equivalent) introduced: a `(index: int, generation: int)` pair | The handle type is exported; can be created and queried |
+| G2 | `MetadataHandleRegistry` (or equivalent) introduced: stores `index -> generation` mapping | The registry has O(1) lookup, bump-generation, and get-with-validation methods |
+| G3 | Production `Metadata` is wrapped in a handle at the consumer entry points | Consumers can do `handle.registry_lookup()` instead of `if entry.lifetime != current_lifetime: ...` |
+| G4 | 1 behavioral test for the handle | `tests/test_metadata_generational_handle.py` exists; asserts lookup, generation mismatch returns `NIL_METADATA`, bump invalidates cached lookups |
+| G5 | Budget gate met: effective-codepaths drop ≥ 20% vs post-child-1 measurement | Re-measurement shows the drop |
+
+## Non-Goals
+
+- Touching the 4 other `dict[str, Any]` aliases — out of scope (deferred to follow-up campaign)
+- Touching the list-typed aggregates — out of scope
+- Replacing the 3 candidate placeholders — blocked on `any_type_componentization_20260621`
+- Adding a generational handle for the inner Metadata values within nested structures (the campaign handles the top-level Metadata; nested handles are out of scope)
+- Cache invalidation (that's child 3; this child just provides the identity)
+
+## Functional Requirements
+
+### FR1: Handle + Registry types
+
+In a sensible location (likely `src/aggregate.py` per AGENTS.md §File Naming Convention, OR a NEW module if the user explicitly approves):
+
+```python
+@dataclass(frozen=True)
+class MetadataHandle:
+    index: int
+    generation: int
+
+class MetadataHandleRegistry:
+    def __init__(self) -> None:
+        self._generations: dict[int, int] = {}
+    
+    def register(self, metadata: Metadata) -> MetadataHandle:
+        # returns a new handle with a fresh index + generation
+    
+    def lookup(self, handle: MetadataHandle) -> Metadata | None:
+        # if handle.generation != self._generations[handle.index], return None
+        # otherwise return the stored Metadata (or sentinel for now)
+    
+    def bump_generation(self, index: int) -> None:
+        # invalidate the cached entry for this index
+```
+
+(Exact API up to Tier 2; the contract is: handle + registry with O(1) lookup + generation-based invalidation.)
+
+### FR2: Migrate lifetime-branch code
+
+For each site in `src/` that does lifetime checks (e.g., "is this Metadata still the one I cached?"):
+- Replace with `handle = registry.register(metadata)` + `value = registry.lookup(handle)` + `if value is None: use NIL_METADATA`
+
+### FR3: Behavioral test
+
+`tests/test_metadata_generational_handle.py` with at least 3 tests:
+- `test_register_returns_handle`: assert `registry.register(metadata)` returns a `MetadataHandle` with distinct `index` and `generation`
+- `test_lookup_returns_none_after_bump`: assert `registry.lookup(handle)` returns None after `registry.bump_generation(handle.index)`
+- `test_lookup_returns_none_for_unknown_index`: assert `registry.lookup(MetadataHandle(index=999, generation=1))` returns None
+- `test_lookup_returns_value_for_valid_handle`: assert `registry.lookup(handle)` returns the registered Metadata
+
+## 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 registry methods (per `conductor/code_styleguides/error_handling.md`)
+- NFR7: No new `src/<thing>.py` files (per AGENTS.md) — unless the user explicitly approves; default is to put `MetadataHandle` + `MetadataHandleRegistry` in `src/aggregate.py` or another existing module
+
+## Architecture Reference
+
+- `src/aggregate.py` (the parent module for `Metadata`)
+- `NIL_METADATA` (from child 1) — the fallback returned by `lookup` on generation mismatch
+- `docs/reports/code_path_audit/2026-06-22/AUDIT_REPORT.md` Finding 1 Fix 3 — the Generational Handle proposal
+- `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)
+- The cache (child 3)
+- Runtime profiling (Track F from the previous menu; deferred)
+
+## Verification Criteria (Definition of Done)
+
+| # | Criterion | Verification command |
+|---|---|---|
+| VC1 | `MetadataHandle` and `MetadataHandleRegistry` exist | `grep -rn "class MetadataHandle\|class MetadataHandleRegistry" src/` |
+| VC2 | Production code uses handle + registry at the entry points | `grep -rn "registry.lookup\|registry.register" src/` returns ≥ 1 hit |
+| VC3 | Behavioral test exists and passes | `uv run pytest tests/test_metadata_generational_handle.py -v` |
+| VC4 | Budget gate met | `compute_effective_codepaths(Metadata_profile)` returns number ≥ 20% smaller than post-child-1 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 | The handle breaks code that expects raw `Metadata` | medium | The handle is a wrapper; consumers can extract the raw value via `.value` or similar. Behavioral test verifies backwards-compat for the common cases. |
+| R2 | The registry's lookup is not actually O(1) | low | The registry uses a `dict[int, int]` for `index -> generation`; lookup is O(1) by construction. |
+| R3 | Budget gate fails (drop < 20%) | low | The 3466 branch points include lifetime checks; replacing with handle lookup should drop the count. If not, the SSDL math is wrong. |

conductor/tracks/metadata_generational_handle_20260624/state.toml

@@ -0,0 +1,44 @@
+# Track state for metadata_generational_handle_20260624
+# Child 2 of metadata_ssdl_defusing_20260624 campaign.
+# 3 phases, 3 tasks. BLOCKED_BY child 1.
+
+[meta]
+track_id = "metadata_generational_handle_20260624"
+name = "Child 2: Metadata Generational Handle"
+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"
+
+[blocks]
+# Within the campaign:
+metadata_field_cache_20260624 = "pending child 2"
+
+[phases]
+phase_1 = { status = "pending", checkpointsha = "", name = "Behavioral Test" }
+phase_2 = { status = "pending", checkpointsha = "", name = "Implementation (Handle + Registry + migrations)" }
+phase_3 = { status = "pending", checkpointsha = "", name = "Verification + Budget Gate" }
+
+[tasks]
+t1_1 = { status = "pending", commit_sha = "", description = "Write tests/test_metadata_generational_handle.py with 4 tests (red)" }
+t2_1 = { status = "pending", commit_sha = "", description = "Add MetadataHandle + MetadataHandleRegistry + migrate lifetime-check sites" }
+t3_1 = { status = "pending", commit_sha = "", description = "Run all 6 VCs; capture budget gate measurement; write TRACK_COMPLETION; update state + tracks.md" }
+
+[verification]
+vc1_handle_and_registry_exist = false
+vc2_production_uses_registry = 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_1_measurement"
+expected_drop_pct = 20
+post_child_2_measurement = null