# Global State Ownership Map

## Objective

Write down which store owns each piece of shared state so nothing lives in two places.

A written map of every shared state domain in the app and the single store, cache, or provider that owns it.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Inventory the shared state the app already holds — the signed-in user, the active workspace, the theme, the cart, the open record, the notification count — and name the one place each is read from.
2. Split the map into two columns: state that mirrors something the server owns, and state that only exists in the browser. The first is a cache with a refresh and an invalidation story; the second is genuinely local and needs a reset story instead.
3. For every server-derived entry, record what invalidates it and what clears it on sign-out or workspace switch. An entry with no documented invalidation is a bug waiting for a stale price or a stale permission.
4. Where the same value is currently held in more than one place, pick the owner, and make the other places read from it rather than keep their own copy. Deleting the duplicate is the point of the exercise.
5. Do not treat this as a rewrite. The deliverable is the map plus the removal of duplicated ownership, not a migration to a different state library — swapping the library leaves the same value in three places under new names.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A value held in two stores will drift, and the drift shows up as a price, a permission, or an unread count that disagrees with itself between two panels on the same screen. Every domain needs exactly one owner named in the map.
- Server cache and client state have different lifetimes and must not share a container. A cached list can be thrown away and refetched at any moment; a half-typed filter panel cannot, and putting them together means one policy is wrong for one of them.
- Every entry needs both an invalidation rule and a reset rule, and they are not the same thing. Invalidation says when the cached copy is no longer trustworthy; reset says what happens on sign-out, workspace switch, or an impersonation session ending.
- Lazily loaded parts of the app must be able to join the map without a circular import back to the code that loads them. If a store can only be reached from the root bundle, code splitting quietly pulls the whole thing back in.
- State restored from storage on boot must be validated against the current shape before it is trusted, or a stale entry from an older release will be handed to code that no longer understands it.
- Two tabs open on the same account share persisted state but not in-memory state, and the map must say which entries are expected to converge across tabs and which are deliberately per-tab.
- Anything holding a token, a session, or personal data must be marked in the map so it is obvious what has to be cleared on sign-out.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Every shared state domain in the app appears in the map with exactly one named owner.
- [ ] Server-derived caches and browser-only state are listed separately and stored separately.
- [ ] Each cached domain documents what invalidates it and what clears it on sign-out or workspace switch.
- [ ] No value is held authoritatively in two stores; duplicated copies have been removed rather than kept in sync.
- [ ] Lazily loaded areas register their state without forcing their code into the initial bundle.
- [ ] Entries holding credentials or personal data are marked, and all of them are cleared on sign-out.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.