fix(lists): the schema wire contract was a string client-side and an object server-side

[Adron]

Summary

Closes #75 and #85. One root cause, so one PR.

The client modelled a list's schema as a DSL string. The API models it as an object, and always has.

POST /api/lists  {"title":"…","schema":"Title:text, Year:number"}
→ 400 {"error":"Invalid schema: DSL must be an object","code":"bad_request"}

That is what CreateListRequest.schema: String? was sending. Creating a list with columns from macOS was a hard failure, not a degradation.

#75 as filed — the {data} envelope on GET /api/lists/{id} — turned out to be the least consequential member of the family: nothing shipped calls detail(listId:). The sweep it asked for found the rest.

The envelope map

Probed live against the .env test account. Transcripts in docs/spikes/list-schema-wire-shapes.md.

Route	Live	Client decoded	Consequence
GET /api/lists/{id}	{data:{…, properties[]}}	bare ListDTO	detail() never decoded — #75
GET /api/lists/{id}/schema	{data:{name, description?, fields[]}}	{schema:String}	schema editor + row table dead
PUT /api/lists/{id}/schema	body object; {message, data}	{schema:String}	schema save was a 400
POST /api/lists	201 {message, data}	bare ListDTO	create never decoded
PUT /api/lists/{id}	{message, data}	bare ListDTO	update never decoded
GET /api/users/{u}/lists/{id}	{list, ancestors}	bare ListDTO	public list page never decoded

Four envelope conventions on one resource family. OPTIONS proves the verb and says nothing about any of this.

⚠️ The PUT …/schema response contradicts the OpenAPI 200 example, which shows a bare {properties:[…]}. The capture wins.

Unlike detail(), ListsService.schema(of:) is live code — ListRowsViewModel.swift:162 and SchemaEditorView.swift:268 both call it.

The key/label split is the deeper fix

Row data is keyed by the column's key; label is only the header text:

"rowData": {"title":"Dune","year":1965,"status":"done"}

SchemaField had one name doing both jobs. That was harmless only because the client could not create a schema at all — so every schema in the wild had key == label. The moment #85 is fixed, a column labelled "Publication Year" over a key of year renders every cell empty.

So key and label are separate, ListColumn { key, label } carries both through the table (header from label, subscript from key), and the DSL initialiser sets them equal — which is precisely what the DSL means.

ListDTO.schema was always nil

Documented as "present on detail and create responses". It is present on no captured payload. OwnedList.schemaDescription — shown in the list detail header and in the Markdown export — has therefore always been empty. Now derived from the real columns.

The destructive-change guard

PUT …/schema refuses to drop a column that still holds row data: 400 plus a propertiesWithData array, ?force=true confirms. The client knew nothing about it, so it presented as an unexplained failure.

It now surfaces as ListsError.schemaChangeWouldLoseData, and SchemaEditorViewModel gains pendingDestructiveSave + confirmDestructiveSave(). force is never set on a first attempt — there is no path to a forced write the server did not ask for, and a test asserts the call order is [false, true].

This unblocks #50

work-consolidation.md P2-G recorded the validation/help-text encoding as API-unconfirmed, which is what blocked item 1 of #50. It is confirmed — and it is not DSL syntax at all, just fields:

validationRules { min, max, minLength, maxLength, pattern, options }
helpText · placeholder · isRequired · isVisible · visibilityCondition
defaultValue · displayOrder

The row inspector renders helpText and placeholder here; the editor UI for the rules stays #50's scope.

visibilityCondition — conditional column visibility — was null on every capture, so it is decoded type-erased rather than guessed at. Modelling an unseen shape is exactly how the G21 and G25 defects happened.

Every fixture is captured

Three silent decode defects have now shipped in this client (G21 link metadata, G25 org members, and these two), and all of them had green tests written against invented fixtures. ListSchemaWireShapeTests uses verbatim response bodies, and pins both regressions directly:

func test_givenTheCapturedBody_whenDecodedAsABareList_thenItFails()
func test_givenTheSchemaBody_whenDecodedAsTheOldStringShape_thenItFails()

StubAPIClient now records the encoded request body, without which "sends a string where an object is required" was untestable at the domain layer.

Known limitation, flagged not worked around

The server's propertiesWithData column list cannot be surfaced: APIError.badRequest keeps only the decoded {error} string and the rest of the body is discarded in APIClient. ListSchemaConflictDTO models the full shape, so naming the columns becomes a one-line change once the kit keeps the body. The user still gets the server's own accurate sentence in the meantime.

Verification

• xcodebuild build → ** BUILD SUCCEEDED **
• xcodebuild test (App) → Executed 978 tests, with 0 failures · ** TEST SUCCEEDED ** (was 975)
• swift test InterlinedDomain → Executed 1017 tests, with 0 failures (was 1012)
• swift test InterlinedPersistence → Executed 140 tests, with 0 failures
• swift test InterlinedKit → Executed 483 tests, offline suites green; ⚠️ the 6 env-gated live ContractTests failed with "Too many attempts. Please try again later." — the account was rate-limited by this PR's own recon probing, not a regression.
• Decision 0003 (anchored) → zero hits

Live account hygiene: one throwaway list was created, schema'd twice, given a row, made public for the public-route probe, and deleted. The account is back to its prior state.

🤖 Generated with Claude Code

https://claude.ai/code/session_016gSWb3scYobtxLJioV1qF9

[Adron]

Merge order — verified by actually integrating the stack

I built a throwaway branch off dev and merged the whole stack in order, so this is measured rather than predicted.

#99  fix/xcode27-document-ambiguity   clean
#87  fix/lists-detail-envelope         clean
#101 feat/lists-authoring-g50          clean   (stacked on #87)
#105 feat/saved-list-views-g40         CONFLICTS — 3 files
#106 refactor/apierror-response-body   clean

Result after resolving: ** BUILD SUCCEEDED **, App Executed 1035 tests, with 0 failures, Domain Executed 1039 tests, with 0 failures. The stack is sound; only the one merge needs hands on it.

The three conflicts, and what each actually is

1. ListMappers.swift — a true duplicate. #87 and #105 independently moved ListJSONValue.init(from: ListCellValue) out of ListsService.swift, for the same reason, with near-identical code.

→ Keep one copy, delete the other. Do not merge the hunks — concatenating them produces one function with two case .array bodies and it will not compile. Keep #105's doc comment (it names the second writer, which is the better explanation now one exists) and #87's body (explicit closures, because ListJSONValue.init(from:) is ambiguous against Decodable.init(from:) — #87 hit that and fixed it).

2. ListsService.swift — genuinely additive. Two new ListsError cases, one from each branch (schemaChangeWouldLoseData, invalidViewName), plus their description arms. → Keep both, in both places.

3. ListRowsView.swift — ⚠️ a real semantic overlap, not additive. Both branches changed the same TableColumnForEach line:

• feat(lists): per-column validation and help text, an Add Row form, and the GitHub repo tag #101 changed columns from [String] to [ListColumn], so the header reads column.label and the cell subscript is column.key — that split is load-bearing, because a web-authored column keyed year under the label "Publication Year" renders empty otherwise.
• feat(lists): saved list views — shared/personal, forking, per-user defaults (G40, #81) #105 kept [String] but added .lineLimit(cellLineLimit), driven by the active saved view's density.

→ They compose. Take #101's ListColumn access and #105's cellLineLimit:

TableColumnForEach(columns) { column in
    TableColumn(column.label) { (row: ListRow) in
        Text(row.fields[column.key]?.displayText ?? "")
            .lineLimit(cellLineLimit)
    }
}

Taking either side wholesale loses something real — #105's side reintroduces the key/label bug, #101's side drops the density control.

After the stack lands

#106 left its two consumers unwired to avoid a three-way stack. Once #87, #102 and #106 are on dev, each is one line:

• ListsService.updateSchema → sendCapturingFailure + details(as: ListSchemaConflictDTO.self), so the destructive-change confirmation names the columns
• AppSettingsService → the same, for the 409's current document

ListSchemaConflictDTO already exists for the first.