Skip to content

Queue prioritization

This page explains how the scheduler chooses which observation to run next on a telescope when more than one is eligible. The mechanics cut across every layer of the access model — telescope access grants, queues, queue access grants, observing accounts, and observing grants — so it’s worth reading Telescope access, Observing queues, and Observing accounts first if any of that vocabulary is new.

The short version: every eligible observation gets a ranking chain, and when two observations compete for the same time the scheduler compares their chains level by level. The first level that differs decides. If no level differs, the two are peers and are scheduled together: the scheduler packs the night for the most observing time, and a capped bonus for time spent waiting while eligible favors work that has waited longer, without guaranteeing that the oldest goes first.

queue level → grant level on the queue → root-account level → grant level at each account down to the funding grant

Who controls each level is the whole story:

  • You, the telescope owner, control the first two: the order of your queues, and the level of each queue access grant within a queue (fixed, fair-share, or calendar — your choice per queue; only fixed is live today, see Implementation status).
  • Each grantee controls everything after that, inside its own slice: the level of its root accounts, and the level of every grant on every account it manages. Nothing a grantee configures can change how much time it gets relative to another grantee — that is always your queue configuration’s decision.

Inside a grantee’s slice, ties are the default. Every list of root accounts and of grants on an account starts as a single level; a priority only exists where someone deliberately created a second level. Equal-ranked work is the scheduler’s friend: the more observations at the same rank, the more freedom it has to pack the night efficiently. The two owner-controlled lists are different: queues on a telescope, and grants in a fixed queue, are strict lists with no ties. You never need to create a queue per grantee to control priority — each grantee already has the levels it needs inside its own accounts.


TelescopeAccessGrant ←─ entity ↔ telescope; shares + credits used across ALL queues
│
│ has many
▼
ObservingQueueAccessGrant ←─ entity ↔ one queue; static level + effective level,
│ credits used within the queue
│ referenced by (at most one per telescope per account)
▼
ObservingAccount (root) ←─ one lane per telescope; ordered among the entity's roots
│
│ has an ORDERED list of
▼
ObservingGrant ←─ who may submit (org / group / member), or a bucket,
│ or a delegation to another entity
▼
ObservingAccount (sub) ←─ inherits the root's lanes; its own ordered grants

Each telescope maintains one telescope access grant per entity that has been admitted to observe with it. The grant carries shares — the entity’s ownership fraction, the input to fair-share prioritization — and the credits the entity has used across all queues (timeUsed). It also has timeContested and timeWaiting fields, which nothing updates today; contested-time accounting is kept separately (see how usage is counted).

Once an entity holds a telescope access grant, queue access grants hang off it — one per queue the entity is allowed to use. A queue access grant carries:

  • The queue it applies to, and a back-reference to the telescope access grant (so the entity and the telescope are both implied).
  • order — the static level you set within the queue. Lower is higher priority; 0 is the top. The queue’s active grants form a strict list: no two share a level, and a new grant joins at the bottom.
  • effectiveOrder — the effective level reserved for the dynamic modes. It is never edited directly, and the scheduler does not maintain or read it today.
  • Credits used within this queue (timeUsed), distinct from the telescope access grant’s cross-queue total (timeContested and timeWaiting exist but are not updated).
  • An optional observing-policy reference (recorded, not enforced).

An entity that holds queue access grants bundles them into observing accounts. An account references at most one queue per telescope — picking the account is picking the lane — and may span as many telescopes as the entity has grants on. A root account also carries a level among the entity’s other root accounts, which matters only where two of the entity’s accounts reference the same queue.

Every way into an account is a grant: an owner grant (the whole organization), a group grant, a member grant, an internal bucket, or a delegation to another entity. The account’s grants form an ordered list, and that list is where an entity prioritizes access inside its slice. See Observing accounts → Priority levels.


The fair-share modes below are designed around one accounting rule. The scheduler already measures contested time this way, but only as a logged diagnostic: it does not change the schedule yet.

Usage counts against a grantee’s share only when the time was contested — that is, only when another grantee’s eligible observation was waiting for the telescope at the same time. Time used while the telescope would otherwise have sat idle is free.

This is deliberate, and it is the property to keep in mind when reasoning about “who is ahead”:

  • Idle time is use-it-or-lose-it. If one grantee is the only one with work queued tonight, they can run all night without consuming any of their share. Nobody was harmed; nothing is owed.
  • Hoarding doesn’t work. A grantee cannot sit out for months, “bank” their unused fraction, and then monopolize the telescope while their average catches up. Only contested time moves the ledger, so there is nothing to bank.
  • Shares mean priority under contention, not a guaranteed number of hours. Weather, targets, and demand decide how much absolute time exists; shares decide how the contested part of it divides.

The bookkeeping behind this is a separate, append-only ledger of contested execution, not the timeContested / timeWaiting fields on the grants. Each interval in which two or more grantees had distinct eligible work accrues each of them an entitlement in proportion to their shares, and debits the grantee that was served; a grantee’s balance is taken over a rolling 30 days. Queue fair-share counts only intervals in that queue; telescope fair-share counts them across the telescope’s queues. The ledger is currently charged conservatively: only completed science frames whose placement still matches the scheduler’s recorded evidence are counted.


Each queue chooses exactly one mode, recorded as the queue’s accessPrioritization. The mode is meant to determine how the queue turns its grants into levels — how each grant’s effective level is produced. Only fixed does so today; see Implementation status. The app labels the modes Default, Total usage, Queue usage, and Schedule-driven.

Mode Behavior
Fixed (default) The effective level is the static level you set on each grant. It doesn’t change as time is used.
Telescope fair-share (total_usage) Designed so grantees running behind their shares — measured on contested time across the whole telescope — float to the top. A grantee crowded out anywhere on the telescope catches up here. Your static levels break ties between grantees at the same standing.
Queue fair-share (queue_usage) Same design, measured on the queue-local contested-usage bookkeeping. Fair-share within this queue only; usage elsewhere doesn’t affect standing here.
Calendar (schedule) Designed so levels vary with time instead of with usage: periods on the queue — “weeks A”, “weeks B”, a semester — each assigning the grants their levels for that period, with the static level applying outside every period. Periods cannot be defined yet.

Choosing between the fair-share scopes: use telescope fair-share when the queue should compensate for imbalance elsewhere (“everyone gets their fair share of the telescope, and this queue is where it evens out”); use queue fair-share when the queue is its own self-contained allocation.

Calendar is intended for rotating arrangements — institution X has priority in week one, institution Y in week two, repeating through the year — where the answer to “who goes first” is a date, not a usage history.


For a given telescope, when the scheduler builds the schedule:

  1. Queues, in queue order. The queue’s order defines the priority order of lanes on the telescope — lower values are higher priority, and no two queues share a value. Disabled queues are skipped. Work already running is never pre-empted: higher queues wait for the current task to finish and then take precedence. (The queue’s interrupt flag is not read by the scheduler today.)
  2. Within a queue: grants, by level. In a fixed queue, the static level you set. In a fair-share or calendar queue, every grant is currently an equal peer.
  3. Within a grant: the entity’s root accounts, by their level. Only accounts that reference this queue can appear here, so the entity’s single ordered list of accounts reads correctly on every queue.
  4. Within an account: its grants, by their level — rosters, members, buckets, and delegations in one ordered list. If the winning grant is a bucket or a delegation, the same rule applies again inside the subaccount, and so on down the tree. Each level of the tree is ordered by the managers of the account at that level.
  5. Among equals: peers are scheduled together, by the scheduler’s efficiency model (most observing time first, then target observability, slews, and window quality), with a capped bonus for time spent waiting while eligible.

Two chains are compared only at the first account where they diverge, by the levels of the two grants there. Levels deeper inside a branch never compete with anything outside it, so a branch’s internal ordering can never lift its work ahead of the sponsor’s other grants. Higher levels are scheduled first and their plan is fixed before lower levels are placed around it.

Eligibility filtering applies throughout: observations whose targets aren’t observable now, whose grants or queues are revoked or disabled, or whose funding account or grant has hit a quota are excluded before any of the ordering above happens. Every placed task records the queue access grant and observing grant it was scheduled under; read those first when diagnosing “why didn’t my observation run.”


Levels 3–5 of the chain happen entirely inside one grantee’s slice of one queue. As the telescope owner you never see or configure them, and they can never change how much time that grantee gets relative to anyone else — but it’s worth understanding what your grantees can do:

  • Ordering root accounts. An entity whose accounts share a queue access grant can rank those accounts. A university running a “research” account and an “outreach” account against the same grant can declare that, under contention, research goes first.
  • Ordering grants on an account. The managers of any account rank the grants on it — a faculty group ahead of a student group ahead of the whole organization — and rank buckets and delegations in the same list. A department can put its thesis students ahead of its intro-lab sections without touching you or your queues.
  • Delegations are ranked by the sponsor. The recipient of a delegated subaccount orders everything inside it, but the branch’s own standing among the sponsor’s grants is the sponsor’s decision and is shown to the recipient read-only.
  • Defaults are neutral. Every list starts as one level. Equal-level siblings are peers, scheduled together, with a capped bonus that favors work that has waited longer. Ordering only changes anything when a manager deliberately creates a second level.
  • Quotas never reorder — they only pause. Quotas on accounts and grants are eligibility limits: when one fills, dispatch for that account stalls in place until the window rolls over. See Observing accounts → Quotas.

One practical consequence for observers: an observation’s position in the chain is determined by the account it was submitted through; if it can be funded through more than one grant, the scheduler uses the highest-ranked route. An observer with access to several accounts changes an observation’s standing — and its lane — by choosing a different account.