recall_action_required: define an ordering contract #60

New issue

Open

opened 2026-05-23 20:55:28 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-05-23 20:55:28 +00:00

Owner

Originally filed by @coilysiren on 2026-05-05T07:58:43Z - https://github.com/coilysiren/repo-recall/issues/52

Use case

A consumer (sibling project, external orchestrator) is wiring recall_action_required as a priority queue: pop the top item, dispatch work against it, refresh, repeat. That contract relies on "top of the queue" being a defined thing.

What's there today

ActionRequiredArgs {} is empty. The current handler iterates db::list_repos_with_counts(&conn) and emits one ActionRequiredEntry per (repo, signal) pair via derive_signals. The order out is "whatever order list_repos_with_counts returned, then the order derive_signals checks signals." Stable enough across scans (so item identity holds, per #3's acceptance), but not a documented priority.

A consumer can sort client-side, but two consumers (a polling orchestrator and a human staring at the dashboard) won't agree on "what's at the top" unless the contract is in one place.

What's needed

Pick one:

Server-side ordering. Document the sort order in the tool description (e.g. "ordered by signal severity, then most-recent activity, then repo name") and apply it before returning. Consumers can rely on repos[0] being meaningful.
Explicit no-ordering. Document that recall_action_required returns an unordered set and consumers must sort. Cheaper, but pushes the question of "what does severity mean" onto every consumer.

Server-side ordering is probably the right call - the dashboard already implies an ordering when it sorts action-required repos to the top. Lifting that ordering into the API + documenting it costs little and gives consumers a stable contract.

Acceptance

The recall_action_required tool description names the ordering (or explicitly says "unordered").
If server-side: a small unit test pinning the order across a fixture set.

Cross-refs

#2 / #3 (closed) - the JSON projection and queue contract this builds on.
#41 - re-notify on still-active signals (adjacent: that's a notification concern; this is a queue-shape concern).

_Originally filed by @coilysiren on 2026-05-05T07:58:43Z - [https://github.com/coilysiren/repo-recall/issues/52](https://github.com/coilysiren/repo-recall/issues/52)_ ## Use case A consumer (sibling project, external orchestrator) is wiring `recall_action_required` as a priority queue: pop the top item, dispatch work against it, refresh, repeat. That contract relies on "top of the queue" being a defined thing. ## What's there today `ActionRequiredArgs {}` is empty. The current handler iterates `db::list_repos_with_counts(&conn)` and emits one `ActionRequiredEntry` per `(repo, signal)` pair via `derive_signals`. The order out is "whatever order `list_repos_with_counts` returned, then the order `derive_signals` checks signals." Stable enough across scans (so item identity holds, per #3's acceptance), but not a documented priority. A consumer can sort client-side, but two consumers (a polling orchestrator and a human staring at the dashboard) won't agree on "what's at the top" unless the contract is in one place. ## What's needed Pick one: - **Server-side ordering.** Document the sort order in the tool description (e.g. "ordered by signal severity, then most-recent activity, then repo name") and apply it before returning. Consumers can rely on `repos[0]` being meaningful. - **Explicit no-ordering.** Document that `recall_action_required` returns an unordered set and consumers must sort. Cheaper, but pushes the question of "what does severity mean" onto every consumer. Server-side ordering is probably the right call - the dashboard already implies an ordering when it sorts action-required repos to the top. Lifting that ordering into the API + documenting it costs little and gives consumers a stable contract. ## Acceptance - The `recall_action_required` tool description names the ordering (or explicitly says "unordered"). - If server-side: a small unit test pinning the order across a fixture set. ## Cross-refs - #2 / #3 (closed) - the JSON projection and queue contract this builds on. - #41 - re-notify on still-active signals (adjacent: that's a notification concern; this is a queue-shape concern).

coilysiren added the

label

2026-05-31 01:55:00 +00:00

coilysiren added

and removed

labels

2026-05-31 07:01:10 +00:00

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

coilyco-flight-deck/repo-recall#60

No description provided.

Rows
Columns