Enum CommandKind 

#[non_exhaustive]
#[repr(u8)]
pub enum CommandKind {
    AssertEdge = 0,
    RetireEdge = 1,
    UpsertConcept = 2,
    WriteBulkAtomic = 3,
    RebuildCurrent = 4,
    RegisterModel = 5,
    Shutdown = 6,
    BulkImportChunk = 7,
    WriteConceptsChunk = 8,
    WriteAnalyticsChunk = 9,
    UpsertEmbeddingChunk = 10,
    Archive = 11,
    RebuildFts = 12,
    ShadowRebuild = 13,
    Analyze = 14,
    Rehydrate = 15,
    Checkpoint = 16,
    Optimize = 17,
    Fork = 18,
    ArchiveBranch = 19,
    ShadowSwap = 20,
}

The command kinds the actor can spend a turn on.

One flat enum across both channels rather than one per channel. The question this exists to answer is “which command broke the budget”, and a reader looking at a 400 ms hold does not first want to know which queue it came off. Priority is a property of scheduling; kind is a property of cost.

#[non_exhaustive], added while it was still free (0.12.8, W4.2)

Adding a variant here is a breaking change without this attribute, because a downstream match on CommandKind would stop compiling. That is not hypothetical for this enum: crate::metrics::CommandKind::Rehydrate did not exist until 0.12.9 precisely because adding it was a break, and rehydration reported as Archive for several releases as a result. The codebase has already paid this cost once, which is the argument for paying the attribute now rather than deciding it at 1.0 when the cost is permanent.

Callers must therefore include a _ => arm. In exchange, this enum can grow a variant for a command kind that does not exist yet without a major version.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

AssertEdge = 0

RetireEdge = 1

UpsertConcept = 2

WriteBulkAtomic = 3

RebuildCurrent = 4

RegisterModel = 5

Shutdown = 6

BulkImportChunk = 7

WriteConceptsChunk = 8

WriteAnalyticsChunk = 9

UpsertEmbeddingChunk = 10

Archive = 11

RebuildFts = 12

ShadowRebuild = 13

The fill half of a chunked shadow rebuild — Begin and every Fill chunk (T1.2).

Its own kind rather than folded into RebuildCurrent, because the two have opposite latency profiles and the whole point of the chunked path is that its turns are short — averaging them together would hide exactly the improvement.

Fill-only since 0.14.16 (D-233). Through 0.14.15 this kind also carried the swap turn, which is over budget by construction, so its over_budget count was N(rebuilds) + regressions and could not be decomposed — the counter was a constant, not a signal. The swap is CommandKind::ShadowSwap now, and what is left here is the half that is meant to fit crate::CHUNK_BUDGET. A nonzero count on this kind is therefore a clean canary: a fill chunk ran long, which is a regression and nothing else.

Analyze = 14

Refreshing the query planner’s statistics (0.12.4, D-149).

Its own kind rather than folded into RebuildFts, though both are maintenance on derived state: this one is bounded by PRAGMA analysis_limit and that one is bounded by the size of the concept table, so averaging their holds together would describe neither.

Rehydrate = 15

Moving archived rows back into the hot file (0.12.9, W4.3, D-152).

Its own kind at last. Through 0.12.8 this reported as CommandKind::Archive, on the stated ground that rehydration is the archive path run backwards and shares its budget — true of the budget and false of the attribution, which is what a metrics surface is for. An operator reading a long archive hold could not tell whether the database had archived anything at all, and the two move rows in opposite directions.

The real reason it stayed folded was that adding a variant was a breaking change. #[non_exhaustive] (W4.2) is what removed that obstacle, and this variant is the first thing it bought — which is also the evidence that the attribute was worth adding rather than a precaution against a hypothetical.

Appended at the end, per CommandKind::index: the position of every existing variant is a persisted contract in two languages.

Checkpoint = 16

An explicit PRAGMA wal_checkpoint (0.12.13, W5.2, D-156).

Its own kind because it is the one actor turn that is not a transaction: it moves frames from the WAL back into the main database file, and its duration is a function of how much WAL has accumulated rather than of anything the caller passed. Folding it into any existing kind would make that kind’s hold distribution bimodal for a reason no dashboard could recover.

Appended at the end, per CommandKind::index.

Optimize = 17

PRAGMA optimize — re-analysing only what SQLite believes has drifted (0.13.24, W10.5, D-197).

Split out of CommandKind::Analyze, which covered both from 0.12.4 to 0.13.23. The split is CommandKind::Rehydrate’s lesson applied before the fact rather than after it: D-168 refused to decide Analyze’s budget exemption because the kind was shared, since a judgement made about the explicit call would have landed on the automatic one — close() runs optimize() unconditionally — without ever being made about it.

The two also have genuinely different hold distributions, which is the same argument CommandKind::ShadowRebuild is separate on. crate::Database::analyze does the work unconditionally and its hold tracks the table. This one is a no-op when nothing has moved, so its distribution is bimodal by design and averaging the two together describes neither.

Appended at the end, per CommandKind::index.

Fork = 18

Registering a lineage (0.14.7, §15.4).

Its own kind rather than folded into AssertEdge, though both are one small transaction: a fork writes to branches and nothing else, so its hold is the floor an actor turn can have, and averaging it into a command that touches four tables would flatter that command’s numbers.

Last in declaration order because that order is a persisted contract and new variants go at the end — see CommandKind::index. Grouping it next to RegisterModel, which is where it belongs by kind, would have renumbered nine counters and relabelled the Python histogram’s axes.

ArchiveBranch = 19

Forgetting a lineage (0.14.13, §15.4, D-230).

Its own kind rather than folded into CommandKind::Archive, on D-152’s finding rather than on a fresh argument: the budget really is shared and the attribution is not, and an operator reading a long archive hold could not tell whether the database had archived a backlog of closed intervals or dropped an abandoned branch. The two also have unrelated cost curves — one is a function of how long it has been since the last run, the other of how much was written on one branch.

At the end of the declaration order, per CommandKind::index.

ShadowSwap = 20

The swap turn of a chunked shadow rebuild (0.14.16, D-233).

Split out of CommandKind::ShadowRebuild, which covered both halves from 0.6.0 to 0.14.15. This is the third instance of one shape — CommandKind::Rehydrate out of Archive ([D-152]), CommandKind::Optimize out of Analyze (D-197), this — so the class is named where it can be seen: one CommandKind, one structural hold distribution. A kind covering two is a defect on arrival, to be split in review rather than found by probe.

Here the bimodality is structural rather than workload-dependent, which is what makes it the clearest instance of the three. Index names are global and SQLite has no ALTER INDEX … RENAME, so the shadow cannot carry idx_lc_traversal_cover while the live table still holds that name — the swap is where all three indexes get built, under the write lock. D-082 measured it at 46.8 ms, 15.6× the budget, and it grows with the table.

Exempt, unlike its fill half — see CommandKind::exempt_from_budget, where the criterion is stated.

At the end of the declaration order, per CommandKind::index.

Implementations

impl CommandKind

pub const ALL: &'static [CommandKind]

Every kind, in declaration order. Indexing into the per-kind arrays is by position in this slice, so the two must not drift — which is why the arrays are sized from ALL.len() rather than from a hand-written count.

pub const COUNT: usize

pub const fn index(self) -> usize

This kind’s slot in the per-kind arrays.

Declaration order is a persisted contract (0.12.8, W4.2)

self as usize means the order of the variants above is the order of every per-kind array in this module, and the compiler cannot catch a change to it. Reordering the enum silently reassigns every counter to a different command: the code compiles, the tests pass, and a histogram read after the change attributes archive’s holds to rebuild_fts.

New variants go at the end, always — including at the end of CommandKind::ALL, whose order is what as_str() and the Python surface enumerate. This binds Python too: BUCKET_BOUNDS_MICROS is a module constant there and KindMetrics is built by position, so a reorder here relabels axes in a language the Rust compiler is not looking at.

#[repr(u8)] is on the enum for the same reason — it pins the discriminants to the declaration order rather than leaving them to the compiler — but it pins them to whatever the order is, so it does not make a reorder safe. Only this rule does.

pub const fn as_str(self) -> &'static str

pub const fn exempt_from_budget(self) -> bool

Whether this kind is exempt from crate::CHUNK_BUDGET by contract.

The exemptions are the table in CHUNK_BUDGET’s own rustdoc, and they are carried here so a dashboard can separate “the budget is being broken” from “the budget does not apply and never claimed to”. Counting an archive as a budget violation would make the violation count useless on any database that archives.

The two lists must agree, and since 0.12.9 they are tied together in both directions by the_budget_exemptions_and_their_documented_table_agree — the extra-row direction being the one worth having, since a table row with no code behind it promises a caller an exemption the violation counter is about to disagree with.

The criterion, stated at last (0.14.16, W12.16, D-233)

The register applied one rule three times without naming it, and naming it is what let the fourth case be decided rather than argued.

Exempt means the chunk bound does not apply: the operation is atomic by necessity and has no smaller unit. Counted means the bound applies, so exceeding it is information.

Every exemption on this list was argued that way in its own release, whatever the summary sentence said afterwards. CommandKind::WriteBulkAtomic (D-014) is one statement, and is the kind that exists precisely because the chunked variant is not atomic. CommandKind::Archive (D-012) and CommandKind::ArchiveBranch delete a consistent set or none of it. CommandKind::RebuildCurrent (D-023) re-derives a whole projection in one transaction. CommandKind::Rehydrate (D-152) is one unchunked transaction moving rows back across the file boundary. CommandKind::Checkpoint (D-156) is a WAL boundary. None of them has a smaller unit to chunk into, so 3 ms is not a bound they failed — it is a bound that was never about them. CommandKind::Analyze and CommandKind::Optimize (D-197) do have one: they are bounded work that can take longer or shorter, so exceeding is a fact about this database and worth counting.

The criterion took three tries, and the two that failed are the useful part

v1 — expected-on-healthy is exempt, workload-dependent is not. Falsified by reading D-197 closely rather than by any new measurement: Optimize runs on every close and stays counted. If expectedness decided the question, Optimize would be exempt and it is not.

v2 — if over_budget can differ from turns, count it. Falsified by three of the exemptions themselves: an Archive with nothing archivable, a Rehydrate of a single row and a Checkpoint on an empty WAL all come in under budget, so their counters can differ from their turn counts and the rule would un-exempt all three.

Both were observational — read off the outcomes the existing exemptions happened to produce, and so decidable only after the fact. Inapplicability is decidable at design time from what the operation is, which is what a criterion has to be if it is to settle the next case rather than rationalise the last one.

Expected-on-healthy survives as corroboration, not definition: a kind with no smaller unit usually does exceed on every healthy database, so the symptom is a fair sanity check on the diagnosis. Optimize is exactly the case that shows why it cannot be the test itself.

over_budget is incremented once per turn that exceeds, so it counts occurrences and not magnitude. That is the fact the criterion turns on: a kind whose every turn exceeds contributes a constant to MetricsSnapshot::budget_violations and moves not at all when the hold doubles. Growth is visible in this kind’s histogram and KindSnapshot::longest, which no exemption touches.

The two halves of a shadow rebuild land on opposite sides of it

CommandKind::ShadowSwap is exempt: ≥ 15.6× by construction (D-082 measured 46.8 ms against a 3 ms budget), with no healthy state in which it fits, and routine — the crate’s own end-to-end suite triggers one. Counting it would put a permanent N(rebuilds) in the violation list of every database that has ever repaired its projection, which is CommandKind::Rehydrate’s argument exactly.

CommandKind::ShadowRebuild — the fill half — is not exempt, and that is the half D-082 was protecting when it refused to exempt the merged kind: “exempting the kind would hide the first fact to excuse the second.” The goal is reaffirmed and the mechanism superseded. The split protects fill structurally, where non-exemption of the merged kind only protected it in principle: a fill regression used to arrive as +1 on a counter that already read N(rebuilds), and now it is the only thing that can move shadow_rebuild off zero at all.

a_swap_over_budget_is_not_a_violation is what keeps this honest, and its fixture is the load-bearing part: it seeds enough of a graph to put the swap over the budget, asserts that first, and only then asserts the swap’s own count is zero. The obvious form — run a rebuild, assert the violation list is empty — is worthless twice over. On a small fixture the swap finishes inside 3 ms and the assertion passes whether the kind is exempt or not; on a real one the fill chunks exceed the budget legitimately (3.14 ms at 200 keys in a debug build), so an empty list is a property of small fixtures rather than of rebuilds.

The two tests are one instrument with two asymmetric halves, and it is worth being exact about which owns what. a_swap_over_budget_is_not_a_violation owns narrowing: re-count the swap and its assertion moves off zero. It cannot own widening, because widening an exemption only ever removes entries from MetricsSnapshot::budget_violations — an assertion that a count is zero stays green under every widening, including one that swallows the fill half whole. Widening is owned by a_long_fill_is_a_violation_and_a_long_swap_is_not below and by nothing else, because forging a long fill and asserting it is counted is the only shape of assertion a widening can break.

Any claim about fill and this budget must name a build mode and a fixture size

At fixture scale the 3 ms bound sits inside fill variance rather than above it, so the same assertion is true or false depending on how the binary was compiled and how much graph it was handed. Debug especially: 200 keys × 4 generations puts the longest fill at 3.14 ms — one violation, the counter working — while a release build of the same shape stays under. A test that asserts anything about fill overages is therefore asserting something about its own fixture and profile, and has to say which. The swap is the opposite and that is why the exemption is testable at all: it exceeds by 15.6× and it exceeds in every mode.

Rehydrate is exempt, and splitting it out is what made that a

decision rather than an accident (0.12.9, W4.3, D-152)

Until 0.12.8 rehydration reported as CommandKind::Archive and was therefore exempt by inheritance — nobody had decided it, it fell out of the borrowed kind. Giving it its own variant would have silently flipped it to non-exempt, and since a rehydrate is one unchunked transaction moving rows back across the file boundary, every single one would have counted as a budget violation. The violation count would then have become useless on any database that rehydrates, which is precisely the failure the Archive exemption exists to prevent, arriving by the back door of a change made for attribution.

So it is exempt, on the merits and now on the record: rehydration is the archive path run backwards and makes the same claim about its hold — that it is bulk movement with no latency bound, and that the caller asked for it explicitly.

Neither CommandKind::Analyze nor CommandKind::Optimize is

exempt, and since 0.13.24 those are two decisions (W10.5, D-197)

They were one kind from 0.12.4 to 0.13.23, and D-168 declined to decide the exemption because they were: Analyze covered crate::Database::optimize too, close() calls that unconditionally, and so a judgement made about the explicit call would have landed on the automatic one without ever being made about it. That is CommandKind::Rehydrate’s lesson above arriving from the other direction — there a shared kind granted an exemption nobody had decided; here one would have laundered one. W10.5 split the kind so each could be answered on its own evidence. Both answers came back the same and the reasons are different, which is the whole reason the split had to come first.

CommandKind::Analyze cannot state a Bound, so it cannot have a row. ANALYZE is one indivisible statement whose cost is set by data volume — measured at 5.26 ms at 10,000 edges and 19.1 ms at 40,000 against a 3 ms budget (examples/analyze_hold.rs, D-166). Every call is a violation and always will be. Checkpoint’s bound is frames accumulated since the last one; Archive’s is the session’s row count. The honest entry here would be “the size of the table, damped 3–4× by analysis_limit”, which is not a bound but the absence of one, and a row that cannot fill that column is this table admitting the thing it exists to prevent.

CommandKind::Optimize is not exempt for the opposite reason: its violations are rare and they are the informative ones. Measured (examples/optimize_hold.rs, 40,000 edges): 10.7 ms the first time on a database that has never been analysed, and 90–220 µs every time after — comfortably inside the budget, including immediately after a bulk load that doubled the ledger. It is over budget only when it actually re-analyses something, and then it is over by a lot: 460 ms once the table had grown 25× and SQLite’s staleness ratio finally fired. So the count is bimodal by construction and it is reporting rather than complaining: an optimize in budget_violations() marks the calls that did work, which is exactly what an operator wants to know and exactly what exempting the kind would delete.

The violations are expected and must not be “fixed” by lowering crate::schema::ddl::ANALYSIS_LIMIT. That would buy the number by sampling too little to separate the two source_id-leading indices, which is the entire purpose of having statistics (D-149).

Trait Implementations

impl Clone for CommandKind

fn clone(&self) -> CommandKind

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for CommandKind

impl Debug for CommandKind

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for CommandKind

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for CommandKind

impl Hash for CommandKind

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for CommandKind

fn cmp(&self, other: &CommandKind) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for CommandKind

fn eq(&self, other: &CommandKind) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for CommandKind

fn partial_cmp(&self, other: &CommandKind) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for CommandKind