---
title: Reclaim the Duplicated nfl_week_id Param Overrides
type: task
status: completed
description: >-
  Stop 27 data-view columns re-declaring nfl_week_id with two fields missing, which duplicates its
  681-value list into param_overrides and costs 339,903 bytes, 22.1 percent of the generation
  catalog, then lock the result with a ratchet.
base_uri: user:task/league/reclaim-duplicated-param-overrides.md
created_at: '2026-09-10T23:21:52.372Z'
entity_id: c846a7ed-aaa3-4be6-8408-8855140e7455
finished_at: '2026-09-11T01:35:31.558Z'
observations:
  - ████████████████████████████████████████████████
  - ████████████████████████████████████████████████
  - ████████████████████████████████████████████████
owner_identity_uri: █████████████████████████
priority: Medium
public_read: true
relations:
  - relates [[█████████████████████████-███-████-████-█████-██████-███████]]
tags:
  - user:tag/league-xo-football.md
  - user:tag/software-task.md
updated_at: '2026-09-11T01:35:31.558Z'
visibility_analyzed_at: '2026-11-05T23:49:55.381Z'
---

## Overview

Stop 27 data-view columns from re-declaring `nfl_week_id` with two fields missing, which duplicates its 681-value list into `param_overrides` 27 times and costs 339,903 bytes — 22.1 percent of the whole generation catalog.

Impact: the catalog drops from 1,540,015 bytes to roughly 1,200,000, and a ratchet keeps it there. Ordering: independent of `████████████████████████████████████████`, which split this out. Neither blocks the other, but both touch the catalog's byte figures, so whichever lands second re-measures.

## Background

Measured 2026-09-10:

```bash
NODE_ENV=development node -e "import('./libs-server/data-views/generation/build-data-view-generation-catalog.mjs').then(m => { const c = m.build_data_view_generation_catalog(); console.log(JSON.stringify(c).length, c.columns.length) })"
# 1540015 598
```

Per-field: `param_keys` 20,207, `param_overrides` 608,792, `play_filter_param_keys` 666,488 — together 84.1 percent of the catalog across 441 of 598 columns.

Within `param_overrides`, 710 entries carry a `values` array totalling 471,386 bytes. One param dominates: `nfl_week_id` at 339,903 bytes across 27 columns, 12,589 bytes each. The next largest is `output` at 33,356 across 110 columns.

### Why those 27 duplicate

`build-data-view-generation-catalog.mjs:316-324` adds a param to `param_overrides` only when its definition differs from the shared registry:

```js
if (!shared || JSON.stringify(shared) !== JSON.stringify(normalized)) {
  param_overrides[param_key] = normalized
}
```

The 27 columns carry an `nfl_week_id` definition MISSING `data_type` and `dynamic_types`, which trips the inequality and duplicates the whole 681-value array.

The obvious hypothesis — that the client field registry causes it — is FALSE, and a control settles it. Rebuilding with `column_params_from_client: {}` makes duplication WORSE: 27 duplicating columns become 132 and the catalog grows to 2,710,937 bytes. The client registry is what suppresses duplication; the remaining 27 are the columns it does not cover.

### Assumptions

- The catalog carries no total-byte assertion today, so the ratchet is new rather than a tightening. Checked: `data-views.generation-context-budget.spec.mjs` asserts only per-tool-answer budgets (16,000 and 8,000), and `data-views.generation-catalog-param-coverage.spec.mjs` asserts coverage counts.
- `describe_column` returns a param UNSUMMARIZED when requested by name, which no budget covers. Checked: `describe-column.mjs:138` reads `requested ? definition : summarize_param_definition(definition)`.
- Removing a duplication changes only serialized bytes, not the params a column offers. UNCHECKED; the first step establishes the before/after param-key set per column.

## Design

Make the 27 columns reference the shared `nfl_week_id` definition instead of re-declaring a partial copy, then lock the result with a ratchet.

The ratchet has two clauses. A total-catalog byte ceiling, which nothing asserts today. And a duplication clause: no param whose value list exceeds a stated option count may appear in `param_overrides` on more than a stated number of columns — this is the clause that would have caught the defect, where a raw byte ceiling only catches its size.

`describe_column` called WITH `param_keys` is uncapped, and `describe-column.mjs:33-35` documents that as deliberate ("a caller that genuinely needs every value asks for the param by name"). This task does NOT ratchet against it; changing that contract means reopening the documented decision, which belongs with whoever owns the agent rail.

### Knowledge Base Impact

- `docs/guides/data.md:43-58`: the measurement block and table are stale at 1,451,970 over 597 columns, 440 of 597 carrying params, and an 85.3 percent share. Correct to the re-measured post-reclaim figures, not the pre-reclaim ones.

### Scope calls

No DDL. No scratch slug. One task entity.

## Plan

### Reclaim

- [ ] **Establish the per-column param baseline**
  - Purpose: prove the reclaim changes bytes only, not behavior.
  - Changes: dump each of the 27 columns' resolved `param_keys` and `param_overrides` key sets to a file before any edit.
  - Verify: the dump exists and names all 27 columns; record the command in this body.

- [ ] **Make the 27 columns reference the shared definition**
  - Files: the field registry entries declaring a partial `nfl_week_id`, identified from the baseline dump
  - Purpose: 339,903 bytes from two missing fields.
  - Changes: complete or remove the partial re-declaration so `JSON.stringify(shared) === JSON.stringify(normalized)` holds.
  - Verify: the count of columns carrying `nfl_week_id` in `param_overrides` falls from 27 to 0, total catalog bytes fall by roughly 339,903, and the per-column param-key sets are byte-identical to the baseline dump.

### Ratchet

- [ ] **Add the catalog ratchet**
  - File: `test/data-views.generation-context-budget.spec.mjs`
  - Changes: assert a total catalog ceiling of 1,300,000 bytes, and assert that no param with more than 100 declared values appears in `param_overrides` on more than 2 columns.
  - Verify: prove each clause red — the ceiling by reverting the reclaim, the duplication clause by re-introducing one partial re-declaration — and show the two readings differ from the passing case.

### Knowledge Base Updates

- [ ] **Correct the catalog figures**
  - File: `docs/guides/data.md`
  - Changes: update the measurement block and table from 1,451,970 over 597 to the re-measured values, with the columns-carrying-params count and the percentage share recomputed after the reclaim lands.
  - Verify: every figure reproduced by the commands already embedded in that section, run after the reclaim; record the date.

### Testing and Validation

- [ ] **Full suite pass**
  - Changes: `yarn test:isolated`, `yarn lint`, `yarn check:cluster`.
  - Verify: green, with the generation catalog specs exercised and `check:cluster` re-run at tick time.