instar 1.3.85 → 1.3.86

package/upgrades/side-effects/attention-api-vocabulary-compatibility.md

@@ -0,0 +1,126 @@
+# Side-Effects Review — Attention API vocabulary compatibility
+
+**Version / slug:** `attention-api-vocabulary-compatibility`
+**Date:** `2026-05-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `self-audit; subagent not spawned by tool policy`
+
+## Summary of the change
+
+This change adds a route-boundary normalizer for Attention Queue status and
+priority vocabulary. Canonical read/store values stay uppercase, while write
+requests may use documented aliases such as `resolved`, `medium`, `body`, and
+`source`. Generated guidance is also corrected to show the required stable item
+id. Files touched include `src/server/attentionApi.ts`, `src/server/routes.ts`,
+the generated guidance templates, and unit/integration/e2e tests.
+
+## Decision-point inventory
+
+- `PATCH /attention/:id` — modified — accepts documented aliases before calling
+  the existing status updater.
+- `GET /attention?status=...` — modified — accepts status aliases for filtering.
+- `POST /attention` — modified — accepts documented create-field aliases before
+  the existing tone-gated create path.
+- Attention topic-flood guard — pass-through — no threshold, coalescing, or
+  topic creation behavior is changed.
+
+---
+
+## 1. Over-block
+
+The change reduces rejection of legitimate documented request shapes. It does
+not add new block conditions. Unknown statuses and priorities still reject on
+write, which is appropriate because the server cannot safely infer arbitrary
+lifecycle states.
+
+---
+
+## 2. Under-block
+
+The alias layer broadens accepted write vocabulary. The main residual risk is an
+operator using an ambiguous word outside the alias set; those values still
+reject. The accepted aliases map only to existing canonical values, so no new
+state can bypass lifecycle handling.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The fix belongs at the HTTP route boundary. Internal storage and Telegram topic
+commands already use canonical statuses; external callers and generated
+guidance use friendlier names. Normalizing at the boundary preserves internal
+consistency without forcing every caller to know storage vocabulary.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [x] Yes — but this is hard-invariant API validation over a finite enum.
+- [ ] Yes, with brittle logic — STOP. Reshape the design.
+
+This is not a judgment gate. The route validates and normalizes finite API enum
+values, which is one of the hard-invariant validation cases allowed by the
+principle. It does not inspect message meaning or add a new block authority.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The normalizer runs before existing `updateAttentionStatus` and
+  `createAttentionItem` calls. Canonical values pass through unchanged.
+- **Double-fire:** No additional Telegram send, topic creation, callback, or
+  persistence path is added.
+- **Races:** No shared mutable state is introduced; normalization is pure.
+- **Feedback loops:** Internal release-readiness resolution calls that already
+  send `resolved` now work against the route instead of failing.
+
+---
+
+## 6. External surfaces
+
+The `/attention` write surface becomes more permissive for documented aliases.
+The read surface remains canonical uppercase. Generated AGENTS/CLAUDE guidance
+will include a stable `id` in new installs and migrations. No existing attention
+state is rewritten. No new attention items are created by the verification path.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal hot-fix revert. There is no data migration. If reverted,
+documented lowercase resolve calls and create aliases would fail again until a
+replacement patch lands.
+
+---
+
+## Conclusion
+
+The fix aligns the documented write vocabulary with the canonical read/store
+vocabulary without changing topic creation policy or existing state. The
+three-tier tests cover the compatibility path and keep the topic-facing effects
+stubbed during verification.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** `self-audit; subagent not spawned by tool policy`
+**Independent read of the artifact: concur**
+
+The compatibility layer is intentionally limited to finite enum and field-name
+aliases. It does not create automatic item ids, because stable ids are part of
+the queue's dedupe discipline; the docs now show that requirement explicitly.
+
+---
+
+## Evidence pointers
+
+- Read-only live inspection found 9 existing attention items using statuses
+  `OPEN` and `DONE`, priorities `HIGH` and `NORMAL`, and no suppressed-topic log
+  present.
+- Focused verification:
+  `npx vitest run tests/unit/attention-api-normalization.test.ts tests/integration/attention-route-vocabulary.test.ts tests/e2e/attention-queue-vocabulary-lifecycle.test.ts tests/unit/SeedMigration.test.ts`