# Mutable Metadata v4 Testing Review Reviewed: - `plans/mutable.metadata.plan.combo.v4.md` - `plans/mutable.metadata.plan.combo.v4.tracking.md` ## Findings 1. High: `GET /custom-metadata/version` and `GET /custom-metadata/history` are externally facing endpoints in the plan, but the tracking doc does not explicitly carry them into Milestone 2 integration coverage. Plan evidence: - `plans/mutable.metadata.plan.combo.v4.md:950-976` defines both endpoints. - `plans/mutable.metadata.plan.combo.v4.md:1584` requires HTTP-level integration tests for all new `/custom-metadata/*` endpoints. Tracking evidence: - `plans/mutable.metadata.plan.combo.v4.tracking.md:339-340` adds handler-level TDD coverage only. - `plans/mutable.metadata.plan.combo.v4.tracking.md:351-360` does not call out either endpoint in Milestone 2 integration tests. - `plans/mutable.metadata.plan.combo.v4.tracking.md:356` references `/custom-metadata` generically, but does not explicitly track `/version` or `/history` route/method cells. Why this matters: - Milestone 2 can be marked complete without HTTP-level proof that version lookup, history pagination, and role gating work on those two routes. Recommended tracking fix: - Add explicit Milestone 2 integration tasks for: - `GET /custom-metadata/version` happy path - `GET /custom-metadata/history` happy path with pagination assertions - authorization cells for both routes 2. High: The `GET /document/{id}` enrichment is documented as a user-visible feature and explicitly called out for integration verification in the plan, but the tracking doc only carries it at unit/controller level. Plan evidence: - `plans/mutable.metadata.plan.combo.v4.md:686-708` defines the externally visible `customSchemaId` and `hasCustomMetadata` additions. - `plans/mutable.metadata.plan.combo.v4.md:1530` says Milestone 2 integration tests should verify that `GET /document/{id}` reflects the new fields. - `plans/mutable.metadata.plan.combo.v4.md:722` includes `GET /document/{id}` enrichment in the metadata-read authorization surface. Tracking evidence: - `plans/mutable.metadata.plan.combo.v4.tracking.md:342-346` covers builder/controller TDD only. - `plans/mutable.metadata.plan.combo.v4.tracking.md:351-360` has no explicit Milestone 2 integration item for `GET /document/{id}`. - `plans/mutable.metadata.plan.combo.v4.tracking.md:356` does not explicitly cover the existing `document` resource behavior for this modified endpoint. Why this matters: - The modified read path could regress, or be wired to the wrong resource behavior, without blocking milestone signoff. Recommended tracking fix: - Add explicit Milestone 2 integration tasks for: - document with no schema -> `customSchemaId: null`, `hasCustomMetadata: false` - document with schema but no metadata -> bound schema ID, `hasCustomMetadata: false` - document with schema and metadata -> bound schema ID, `hasCustomMetadata: true` - role coverage confirming `GET /document/{id}` remains on the existing `document` resource behavior 3. High: The reset-metadata endpoint's documented HTTP contract is only partially tracked at integration level. Plan evidence: - `plans/mutable.metadata.plan.combo.v4.md:620-673` documents the endpoint, including `200`, `404`, and `409` behaviors. - `plans/mutable.metadata.plan.combo.v4.md:1612-1619` explicitly requires integration coverage for the happy-path response assertions, legacy-extraction guard (`409`), and document-not-found (`404`). Tracking evidence: - `plans/mutable.metadata.plan.combo.v4.tracking.md:389-415` covers these branches at service/handler TDD level. - `plans/mutable.metadata.plan.combo.v4.tracking.md:419-423` only tracks the upgrade flow, already-clean idempotency case, schema-version concurrency, auth matrix, and fullsuite gate. Why this matters: - Milestone 3 can be declared complete without HTTP-level verification of two documented error responses. - The current happy-path integration item also under-specifies the response assertions the plan requires (`previousSchemaId`, `previousSchemaName`, `previousSchemaVersion`, `metadataVersionsDeleted`, and the post-upgrade `GET /document/{id}` check). Recommended tracking fix: - Add explicit Milestone 3 integration tasks for: - reset on legacy-extraction document -> `409`, DB unchanged - reset on non-existent document -> `404`, DB unchanged - reset happy path asserts the documented response fields and verifies the follow-up `GET /document/{id}` state after rebind 4. Medium: Two documented HTTP behaviors are tracked only below the integration layer: clearing a document schema binding with `customSchemaId: null`, and the server-derived actor identity contract on write endpoints. Plan evidence: - `plans/mutable.metadata.plan.combo.v4.md:571-576` documents `PATCH /super-admin/documents/{id}/schema` with `customSchemaId: null` removing the binding when no metadata exists. - `plans/mutable.metadata.plan.combo.v4.md:867-869` and `plans/mutable.metadata.plan.combo.v4.md:1604` make actor identity a user-visible contract: request-body `createdBy` is ignored, stored/returned actor fields come from the JWT subject. Tracking evidence: - `plans/mutable.metadata.plan.combo.v4.tracking.md:293` tracks the null-unbind path at service TDD level, but `plans/mutable.metadata.plan.combo.v4.tracking.md:351-360` has no HTTP integration item for it. - `plans/mutable.metadata.plan.combo.v4.tracking.md:194`, `plans/mutable.metadata.plan.combo.v4.tracking.md:336`, and `plans/mutable.metadata.plan.combo.v4.tracking.md:411` track actor handling in controller/handler tests, but no milestone integration section explicitly carries the contract. Why this matters: - The API could pass service/controller tests while still missing the actual HTTP request/response behavior promised to callers. Recommended tracking fix: - Add a Milestone 2 integration case for `PATCH /super-admin/documents/{id}/schema` with `{"customSchemaId": null}` on a pre-bound document with no metadata. - Add integration cases for the write endpoints that expose actor fields in persisted data or responses, at minimum `POST /super-admin/custom-schemas`, `POST /super-admin/custom-schemas/{schemaId}/versions`, `POST /custom-metadata`, and `POST /super-admin/documents/{id}/reset-metadata`. ## Verified - The tracking doc already encodes the fail-first TDD rule and the "do not mark done until tests pass" rule: - `plans/mutable.metadata.plan.combo.v4.tracking.md:5` - `plans/mutable.metadata.plan.combo.v4.tracking.md:26` - `plans/mutable.metadata.plan.combo.v4.tracking.md:31` - `plans/mutable.metadata.plan.combo.v4.tracking.md:508-510` - I did not find conflicting language that would allow a checkbox or milestone to be marked complete before the associated tests are passing.