Files
pad/internal/server
xarmian d18a5d8140 refactor(bootstrap): omit redundant schema labels + omitempty sort_order (TASK-1424) (#543)
Two small additive trims to the BootstrapCollection projection
introduced in TASK-1412.

## 1. Omit redundant schema `label` when label == TitleCase(key)

A schema field's `label` is auto-fillable from its `key` (the CLI
and the MCP-side CreateCollection helper both apply
TitleCase(key) when label is empty — see titleCaseLabel in
internal/mcp/dispatch_http_routes.go). When the persisted label
matches that rule, it's redundant — the agent can reconstruct it
from the key. Examples on docapp:

  - {"key":"status",   "label":"Status"}   ← redundant
  - {"key":"due_date", "label":"Due Date"} ← redundant
  - {"key":"trigger",  "label":"When"}     ← CUSTOM, preserved

Implementation: projectBootstrapCollection now passes the schema
bytes through trimRedundantSchemaLabels, which:

  1. Unmarshals into a parallel bootstrapSchema/bootstrapFieldDef
     struct purpose-built for the bootstrap shape.
  2. Walks fields, clears any Label that equals TitleCase(Key).
  3. Re-marshals — `omitempty` on bootstrapFieldDef.Label drops
     the empty-string labels from the output.

Field ordering is preserved by struct-based marshalling.

## 2. Omitempty on BootstrapCollection.SortOrder

`sort_order` defaults to 0. Most collections never get an explicit
non-zero sort_order, so the field carried "sort_order":0 per entry
needlessly. Added ,omitempty to the struct tag.

## Drift detection

bootstrapFieldDef mirrors models.FieldDef field-for-field with two
deliberate differences: `Label` is omitempty, and `Default` is
json.RawMessage (so any default value round-trips verbatim
without re-parsing). The risk: if models.FieldDef gains a new
field, bootstrapFieldDef silently loses it from the bootstrap
schema response.

TestBootstrapFieldDefMirrorsModelsFieldDef catches this via
reflection — compares NumField + per-field JSON tags + has an
explicit allow-list for the Label tag delta. A new field added to
models.FieldDef without mirroring here fails the test with a
field-name-pointed error message.

## Test coverage

  - TestBootstrapFieldDefMirrorsModelsFieldDef — drift detector.
  - TestTrimRedundantSchemaLabels (4 subtests):
    * drops-redundant-labels
    * preserves-custom-labels (key="trigger", label="When" stays)
    * multi-word-keys-titlecase-correctly (due_date → Due Date)
    * malformed-schema-returns-raw (defensive: never block on parse error)
  - Existing TestBootstrapSizeBudget shows fixture collections
    section drop: 3,979 → 3,532 bytes (-11.2%).

## Measurements

Fixture (TestBootstrapSizeBudget): 7,823 → 7,376 bytes (-447 b / -5.7%).
Collections section alone: 3,979 → 3,532 bytes (-447 b / -11.2%) —
all of the win is concentrated in schema bytes via the label trim.

Live docapp expected savings: 9,384 → ~8,400 bytes (~10% drop on
collections), totaling roughly 600-900 b additional reduction on
the bootstrap response.

## Out of scope

- ToolSurfaceVersion 0.3 → 0.4 bump — TASK-1418 (the FINAL PR in
  PLAN-1410). This is the last shape PR; TASK-1418 is now unblocked.

Parent: PLAN-1410. With this merged, PLAN-1410's bootstrap-shape
work is complete; only the contractual v0.4 announcement remains.
2026-05-13 17:34:57 -04:00
..