Watchers: User and state model

Defines explicit watcher membership, reasons, notification preferences, authorization changes, event identity, mute/unwatch behavior, and privacy-safe counts for collaborative resources.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Represent watching as a user-resource relationship with source, state, and preference. Evaluate current visibility before every notification, and separate watcher membership from delivery-channel subscription so users can mute without losing their relationship.

Scope

• Watch, automatic watch, unwatch, mute, membership, preferences, resource lifecycle, authorization, notifications, counts, and audit.
• Users following changes to projects, issues, documents, or threads.
• User and state behavior across devices.

Outside this block

• General notification retry infrastructure.
• Exposing identities or counts when membership is private.

Contract

• A watcher record has user, tenant, resource, source, created time, membership state, and notification preference/version.
• Manual watch is idempotent; automatic watch reasons are visible and can be overridden according to product policy.
• Mute stops future notification creation for the selected scope while watch membership remains active.
• Unwatch removes active membership and pending notifications not yet handed off, subject to mandatory-notice policy.
• Current authorization and resource visibility are checked before event fan-out and again before sensitive rendering.
• Watcher lists and counts follow visibility policy and cannot reveal restricted participants.

Implementation guidance

• Use unique active relationship identity and append state transitions for audit.
• Fan out from one stable resource event ID and deduplicate (event, watcher, channel).
• Record preference snapshot or version used for each notification decision.
• Clean up or suspend watchers on resource deletion, membership removal, account closure, and tenant transfer.

Failure handling and safeguards

• If authorization lookup fails, suppress protected notification and retry safely.
• If user membership is removed after fan-out, rendering or delivery rechecks and suppresses content.
• If automatic watch policy changes, do not silently re-enable a user's explicit mute or unwatch.

Verification and operations

• Measure watch/unwatch/mute, auto-watch override, fan-out size, suppressed-by-auth, suppressed-by-preference, duplicate creation, and stale watcher cleanup.
• Test hidden watcher lists and counts with users of different roles.
• Review noisy event types through mute and unwatch behavior.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• No external normative source is required; this package defines a project decision.