0003-comparator-semantics

ADR 0003: Priority comparator semantics — package-global vs per-adapter

Status: Proposed

Context

Some adapters and frontends expect semantic ordering for project priorities (critical > high > medium > low).

Historically the code used a package-global comparator which is not thread-safe and prevents multiple adapters from using different orderings simultaneously.

Decision

Introduce an optional per-adapter comparator field on memory.GenericAdapter that, when set, takes precedence over the package-global comparator.

Protect the package-global comparator with an RWMutex to allow safe concurrent reads and occasional writes.

Provide a package-level SetPriorityComparator for legacy/global behavior and an adapter-level SetPriorityComparator for per-instance configuration.

Consequences

Multiple adapters running in the same process may have different priority semantics (useful for testing and mixed upstream systems).

Legacy callers that relied on the package-global comparator will continue to work but should migrate to per-adapter configuration when running multiple adapters concurrently.

Related

internal/adapter/memory/sort.go

internal/adapter/memory/memory.go

Date: 2025-09-11 Author: Automated refactor agent