|
| 1 | +# Item PUT and change-feed audit |
| 2 | + |
| 3 | +Date: 2026-08-25 |
| 4 | + |
| 5 | +## Scope |
| 6 | + |
| 7 | +Reviewed cookie API and bearer v1 `PUT` routes whose primary resource is a work |
| 8 | +item or an item-owned subresource. Also reviewed label assignment and generic |
| 9 | +link create/delete paths because GitHub issue #219 names them explicitly. |
| 10 | + |
| 11 | +The relevant contracts are: |
| 12 | + |
| 13 | +- `items.updated_at` changes when the serialized shared item payload changes. |
| 14 | +- `items.last_active_at` changes for card activity, but not for manual ordering |
| 15 | + or catalog-wide metadata maintenance. |
| 16 | +- Every committed item-row update emits an `item_change_log` row through the |
| 17 | + SQLite/PostgreSQL schema triggers used by `/items/changes`. |
| 18 | + |
| 19 | +## Results |
| 20 | + |
| 21 | +| Operation | Shared item payload | `updated_at` | `last_active_at` | Change feed | Result | |
| 22 | +| --- | --- | --- | --- | --- | --- | |
| 23 | +| `PUT /items/{id}` | Changes | Yes | Yes | Yes | Existing shared update service is correct. | |
| 24 | +| `PUT /items/{id}/labels` | Changes | Yes | Yes | Yes | Fixed in the shared label repository; cookie, v1, CLI, and AI paths inherit it. | |
| 25 | +| `POST/DELETE /items/{id}/labels...` | Changes | Yes | Yes | Yes | Fixed with the same transactional assignment contract. A missing-label removal remains a no-op. | |
| 26 | +| `PUT /labels/{id}` | Changes labels nested in assigned items | Yes | No | Yes | Fixed by invalidating assigned items in the label transaction without bubbling every card. | |
| 27 | +| `DELETE /labels/{id}` | Removes labels nested in assigned items | Yes | No | Yes | Fixed before the assignment cascade in the same transaction. | |
| 28 | +| `POST/DELETE /links...` | Changes item detail links | Yes, for every item endpoint | Yes, for every item endpoint | Yes | Fixed transactionally. Single-value replacement also invalidates the removed target. | |
| 29 | +| `PUT /items/{id}/frac-index` | Changes manual order only | No | No | Yes | Intentional. The item-row trigger propagates ordering while timestamps stay stable. | |
| 30 | +| `PUT /comments/{id}` | No; comment is fetched separately | No | Yes | Yes | Intentional. Comment activity touches the item and has its own resource timestamp. | |
| 31 | +| `PUT /items/{id}/recurrence` | No; recurrence is fetched separately | No | No | No | No parent invalidation required by the item payload contract. | |
| 32 | +| `PUT /diagrams/{id}` | No; diagrams are fetched separately | No | No | No | No parent invalidation required; diagram history and timestamps are recorded on the diagram resource. | |
| 33 | +| `PUT /items/{id}/personal-labels` | Viewer-specific data | No | No | No | Intentional. Per-user metadata must not mutate shared item activity for every viewer. | |
| 34 | + |
| 35 | +## Transaction boundaries |
| 36 | + |
| 37 | +Label assignments now update the junction table and item timestamps in one |
| 38 | +transaction. Generic link creation, deletion, and single-value replacement do |
| 39 | +the same for every affected item endpoint. A timestamp/change-feed failure |
| 40 | +therefore rolls back the relationship mutation instead of returning a partial |
| 41 | +success. |
| 42 | + |
| 43 | +Jira import continues to attach labels without touching item activity so the |
| 44 | +imported source timestamps remain intact. GitHub issue sync already replaces |
| 45 | +labels inside the transaction that updates the item itself. |
0 commit comments