# Kit Subscriber Sync

## Objective

Send subscribers to Kit with the form, tags, and fields matching how they signed up.

A sync that maps each app signup path to a specific Kit form or sequence and keeps subscriber fields and tags aligned.

## 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. Enumerate the distinct ways someone becomes a subscriber in the app — each signup form, lead magnet, checkout, and import — and map each one to exactly one destination form or sequence, configured rather than hardcoded.
2. Store the provider's subscriber ID alongside the local record and use it for subsequent updates, but keep the app's own user or lead ID as the identity of record. The provider ID identifies a subscription, not a person.
3. Make every enrollment idempotent using a key derived from the subscriber and the destination, so a retried job confirms the existing enrollment instead of adding a second one.
4. Read the subscriber's current state before writing. Someone who unsubscribed must stay unsubscribed, and a new signup by an unsubscribed address needs a fresh, recorded opt-in before you resubscribe them.
5. Do not resolve tags and forms by name at send time. Names get edited, and a rename will quietly create a new tag while the old one keeps its audience — resolve to stable identifiers at mapping time and re-validate them.

## 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

- One app signup can plausibly belong to several forms or sequences. Force the mapping to pick one destination per entry point, because ambiguity here produces subscribers who receive two overlapping onboarding sequences.
- An unsubscribed address that signs up again is not an instruction to resubscribe. Preserve the unsubscribe, capture the new consent explicitly with a timestamp and source, and only then re-enable sending.
- Job retries and provider retries both re-run enrollment. Without an idempotency key per subscriber and destination, one signup adds the same tag twice and starts the sequence from the beginning again.
- Tags and forms get renamed or deleted between configuration and use. A mapping pointing at something that no longer exists must pause with a message naming it, and must never create a replacement by name on the fly.
- Provider subscriber IDs are not global identity. Two app users sharing a household email, or one user changing their address, will break any model that treats the provider ID as the person — key on the app's own record instead.
- If the app syncs to more than one email provider, exactly one of them must be designated authoritative for consent, and this brief must read that decision rather than making its own. Two providers each restoring the other's unsubscribes is worse than no sync.
- Tokens expire and connections get revoked from the provider side. Hold queued enrollments, show the connection as broken, and resume from the held queue on reconnection.
- When the provider is unreachable, the app's signup must still succeed and the confirmation must not promise an email that has not been queued anywhere.

## 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

- [ ] Each signup path resolves to exactly one configured form or sequence.
- [ ] Retried jobs never add a duplicate tag or restart a sequence.
- [ ] An unsubscribed address is not resubscribed without a newly recorded opt-in.
- [ ] Renamed or deleted tags and forms pause the mapping with a named error rather than being recreated.
- [ ] Provider subscriber IDs are stored as references, and the app's own record remains the identity of record.
- [ ] Consent authority is defined in one place when multiple email providers are connected.
- [ ] A provider outage leaves the signup successful and the enrollment queued.
- [ ] 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.