bunsen 0.42.0

bunsen is a batteries included common library for burn
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
# Using build catalogs

This guide covers the module's API, from importing catalogs to choosing a build, and the select
language that does the choosing. The document form (the keyed `$` form, entry kinds, names,
references, `$merge`) is described in [`catalog_format`](catalog_format). This guide uses as much of it as
selection needs.

The examples run against the example catalogs in `testing::fixtures` (the `testing` feature), which `fixtures::example_stack()`
imports in this order: `prelude`, `commons`, `qwen3`, `whisper`. Their builds (a query's run
starts from them in full-name order: Whisper's `openai/...` first):

| build | family | class chain | thinking | task | parameters | other |
|---|---|---|---|---|---|---|
| `qwen3-0.6b` | `qwen/qwen3` | `hybrid` | switch | | 6e8 | |
| `qwen3-0.6b-base` | `qwen/qwen3` | `hybrid` | never | | 6e8 | `instruct: false` |
| `qwen3-4b-thinking-2507` | `qwen/qwen3` | `hybrid > thinking-only` | always | | 4e9 | in `qwen3-2507` |
| `large-v1` | `openai/whisper` | `multilingual` | | both | 1.55e9 | release 2022-09 |
| `large-v2` | `openai/whisper` | `multilingual` | | both | 1.55e9 | release 2022-12 |
| `large-v3` | `openai/whisper` | `multilingual` | | both | 1.55e9 | release 2023-11-06, `timestamps: true` |
| `large-v3-turbo` | `openai/whisper` | `multilingual` | | transcribe only | 8.09e8 | |

Qwen3's `language` is `["*"]`; Whisper's is `[en, "*"]`. The Qwen3 builds have the contract
`qwen3-lm`, the Whisper builds `whisper-asr`. The supplemental catalog
(`fixtures::supplemented_example_stack()`) adds `qwen3-1.7b`.

## Contents

1. [The pipeline]#the-pipeline
2. [Importing catalogs]#importing-catalogs
3. [Finding entries]#finding-entries
4. [Resolving a build]#resolving-a-build
5. [Presets]#presets
6. [Choosing builds]#choosing-builds
7. [The select language]#the-select-language
8. [The CLI]#the-cli
9. [Lower layers: a query by hand]#lower-layers-a-query-by-hand
10. [Errors]#errors

## The pipeline

```text
catalog documents ──push──▶ BunsenCatalogStack ──resolve_build──▶ ResolvedBuild
                              (validated state)                         (tags, presets, deps)
                                     │
                     SelectEnv: the stack, derive steps, resolved builds
                                     │
     a tool's preset prefix ++ defaults ++ request (`use` spliced) ++ tail
                                     │ SelectionContext::compose
                                SelectQuery ──compile──▶ CompiledQuery
                                     │ run
   universe (full-name order, weight 1) ─▶ stage ─▶ stage ─▶ … ─▶ SelectRun (table, trace)
```

- A **stack** holds the imported catalogs as one validated state. Every query reads it.
- A **resolved build** is everything the state says about one build: its template-class chain,
  its memberships and facets, its tags (written and implied), its presets folded along the
  chain, its contract, and the resources and arguments it binds to the contract's slots.
- A **query** is a kind and a list of stages, written only in YAML particles. Each stage maps a
  table of weighted rows to a table; no stage adds a row. The result is the last table.
- A **choice** is the first row of the result. A query never selects presets: the caller applies
  the presets it chose, and a prefix keeps only the builds they apply to.

## Importing catalogs

A catalog document is the namespace tree, in the keyed form [`catalog_format`](catalog_format) describes:
every key the catalog language defines starts with `$`, and a bare key is a name (a child, a
tag, or a preset).

`BunsenCatalogStack` imports catalogs one after another. A push applies the catalog's
entries, in order, to a copy of the state, validates the whole copy, and commits it only if
nothing is wrong. A refused catalog leaves the stack as it was, and the error lists every
problem found.

```rust
use bunsen::data::catalog::{
    CatalogErrorExt,
    CatalogRule,
    BunsenCatalogStack,
    testing::fixtures,
};

let mut stack = fixtures::example_stack().unwrap();
let labels: Vec<&str> = stack.layers().iter().map(|l| l.label()).collect();
assert_eq!(labels, ["prelude", "commons", "qwen3", "whisper"]);

// A build whose template class doesn't exist is refused, and so is its catalog.
let err = stack
    .push_yaml(
        "broken",
        r#"
orphan:
  $kind: build
  $description: "Names a class nobody declared."
  $template_class: no-such-class
"#,
    )
    .unwrap_err();
assert!(err.has(CatalogRule::Reference), "{err}");
assert_eq!(stack.layers().len(), 4);

// An empty stack, filled from files, or from documents built in code.
let mut empty = BunsenCatalogStack::new();
empty.push_yaml("prelude", fixtures::PRELUDE).unwrap();
```

| call | does |
|---|---|
| `BunsenCatalogStack::new()` | an empty stack |
| `builtin_stack()` | bunsen's built-in catalog |
| `push(label, BunsenCatalog)` | imports a document built in code |
| `push_yaml(label, text)` | parses YAML, then pushes |
| `push_file(path)` | reads YAML (or JSON, by a `.json` extension), labelled by its file stem |
| `layers()` | the imported catalogs, in order, with their labels, paths and documents |
| `occurrences(name)` | every occurrence of a name across the catalogs, in import order |
| `declaration(name).history()` | which catalogs declared, updated and replaced an entry |

The first catalog is usually a prelude: the facets, registered axes and tags, and
`template_class_root`. A catalog can refer to anything below it in the stack, and its extending
occurrences (`$merge: update`) add to groups an earlier catalog declared. `testing/fixtures/supplemental.yml`
shows a local addition.

`builtin_stack()` is bunsen's own catalog, the layers `bunsen-catalog` carries: a prelude whose
`$contracts` are the kits' loaders, the publishers, and a layer per kit, skipping the kits this
build of bunsen leaves out. The catalog builder (`cargo catalog`, in the repository's `validation/`
workspace) writes them from their probe-contract sources, reading the pins from the Hub and the
presets from the checkpoints' files. A local catalog pushes on top of it.

## Finding entries

Names are `/`-separated paths, such as `openai/whisper/large/large-v3`. Lookups accept any
spelling that identifies one entry: the leaf, or a longer path, in any ASCII case. An `alias` entry is another
name for an entry: a lookup for its target's kind finds the target through it.

```rust
use bunsen::data::catalog::{
    CatalogName,
    document::EntryKind,
    testing::fixtures,
    lookup::{
        LeafMatch,
        SEARCHABLE,
    },
};

let stack = fixtures::example_stack().unwrap();

let v3 = stack.find_build("large-v3").unwrap();
assert_eq!(v3.to_string(), "openai/whisper/large/large-v3");
// The shortest spelling that still identifies it, for people.
assert_eq!(stack.display_name(&v3).short, "large-v3");

// Every build has a resource called `checkpoint`, so the leaf alone is ambiguous.
// The error lists the candidates. A longer spelling picks one.
let err = stack
    .find("checkpoint", &SEARCHABLE, LeafMatch::Exact)
    .unwrap_err();
assert!(err.message().contains("large-v3/checkpoint"), "{err}");
let one = stack
    .find("large-v3/checkpoint", &[EntryKind::Resource], LeafMatch::Exact)
    .unwrap();
assert_eq!(one.leaf(), "checkpoint");

// Groups and their members.
let whisper = stack
    .find("whisper", &[EntryKind::Namespace], LeafMatch::Exact)
    .unwrap();
assert_eq!(stack.members_of(&whisper).len(), 4);
// Contracts live in the base catalog's `$contracts`, apart from the
// namespace; a build names one with `$contract`.
let contracts: Vec<String> = stack
    .of_kind(EntryKind::Contract)
    .iter()
    .map(|c| c.name().to_string())
    .collect();
assert_eq!(contracts, ["$contracts/qwen3-lm", "$contracts/whisper-asr"]);
let whisper_asr = CatalogName::parse("$contracts/whisper-asr").unwrap();
assert_eq!(stack.builds_of_contract(&whisper_asr).len(), 4);

// An alias, anywhere in the namespace, is another name for its target.
let mut aliased = stack.clone();
aliased
    .push_yaml(
        "aliases",
        "large: { $kind: alias, $ref: { $path: openai/whisper/large/large-v3, $kind: build } }\n",
    )
    .unwrap();
assert_eq!(aliased.find_build("large").unwrap(), v3);
assert_eq!(aliased.aliases_of(&v3)[0].to_string(), "large");

// Release groups are ordered by release time.
let release = stack
    .find("large/release", &[EntryKind::Release], LeafMatch::Exact)
    .unwrap();
assert_eq!(stack.latest(&release).unwrap(), Some(v3.clone()));
```

| call | does |
|---|---|
| `find(query, kinds, LeafMatch)` | one entry of `kinds`; `LeafMatch::Prefix` lets the last segment be a prefix |
| `find_build(query)` | `find` over builds, with an exact leaf |
| `matches(query, kinds, LeafMatch)` | every entry a query could mean, aliases resolved to their targets |
| `named_as(name, kinds)`, `aliases_of(name)` | what a full name stands for (itself, or an alias's target); the aliases naming an entry |
| `display_name(name)` | `{short, full}`: the least specified spelling that resolves to the entry |
| `declaration(name)` | the entry: `kind()`, `body()`, `history()`, `declared_in()` |
| `of_kind(kind)`, `children(name)` | entries of a kind; the entries in a scope |
| `members_of(group)` | the builds in a group, directly or through other groups and class chains |
| `facet_groups(facet)`, `builds_in_facet(facet)` | "all families"; "builds in some family" |
| `build_memberships(build)` | every group a build is in |
| `template_chain(start, from)` | a class chain, root first |
| `releases(group)`, `latest(group)` | a release group's members by time; its newest |
| `resolve_ref(reference, from)` | a reference as an entry written in `from` would resolve it |

## Resolving a build

`resolve_build` gathers everything the state says about a build into a `ResolvedBuild`.

```rust
use bunsen::data::catalog::{
    CatalogName,
    testing::fixtures,
};
use serde_json::json;

let stack = fixtures::example_stack().unwrap();
let name = stack.find_build("large-v3").unwrap();
let build = stack.resolve_build(&name).unwrap();

// Written tags, and the tags the catalog implies: facets, the contract, axes.
assert_eq!(build.tag("parameters"), Some(&json!(1550000000)));
// A tag declared in a namespace is keyed by its full name.
assert_eq!(build.tag("openai/whisper/timestamps"), Some(&json!(true)));
assert_eq!(build.tag("family"), Some(&json!("openai/whisper")));
assert_eq!(build.tag("contract"), Some(&json!("whisper-asr")));

let chain: Vec<&str> = build.template_chain.iter().map(|c| c.leaf()).collect();
assert_eq!(chain, ["template_class_root", "multilingual"]);
assert_eq!(build.contract, Some(CatalogName::parse("$contracts/whisper-asr").unwrap()));
let release = build.release.as_ref().unwrap();
assert_eq!(release.released.to_string(), "2023-11-06");
// The contract's slots, bound: the build's own checkpoint, its family's
// vocabulary.
assert_eq!(build.resources["checkpoint"].resource.leaf(), "checkpoint");
assert_eq!(build.resources["vocabulary"].set_by.leaf(), "multilingual");
```

| field | holds |
|---|---|
| `name`, `description`, `license`, `origin` | as written |
| `template_chain` | the class chain, root first |
| `memberships`, `facets` | every group the build is in; its group per facet |
| `contract` | its contract, under `$contracts`: its own `$contract`, or the nearest class's |
| `release` | `{group, released}`, when it joins a release group |
| `tags` | each tag's value and source, by full name (`TagSource`: `Written` by the build or the class that writes it lowest in the chain, or implied by an `Axis`, a `Facet` or the `Contract`) |
| `presets` | the folded `ResolvedPresetSet` |
| `resources`, `args` | the contract's resource slots and argument slots, bound: each slot's resource (or value) and who bound it |

## Presets

A build's presets fold down its class chain. An axis use (`{use, offers, default}`) may narrow
what the use above it offered, and when it narrows, the presets of the dropped members are
pruned. A use that offers one member is a fixed mode.

A preset with the name of an inherited one meets it by its `$merge`:

- `update`, the default, merges its patch over the inherited patch, and a description replaces
  the inherited one;
- `replace` takes the inherited preset's place;
- `deny` refuses an inherited preset of its name.

With nothing inherited, the preset is declared, whatever its mode.

```rust
use bunsen::data::catalog::{
    CatalogName,
    testing::fixtures,
    presets::PresetSelection,
};
use serde_json::json;

let stack = fixtures::example_stack().unwrap();
let thinking = CatalogName::parse("thinking").unwrap();

let hybrid = stack
    .resolve_build(&stack.find_build("qwen3-0.6b").unwrap())
    .unwrap();
// The negative member of the bool axis `thinking`.
let off = hybrid.presets.bool_member(&thinking, false).unwrap();
assert_eq!(off, "no-thinking");
let applied = hybrid
    .presets
    .select(json!({}), &PresetSelection::of([off.as_str()]))
    .unwrap();
assert_eq!(applied.document["chat"]["enable_thinking"], json!(false));
assert_eq!(applied.document["generation"]["temperature"], json!(0.7));

// A build that fixes the mode explains why the other member doesn't apply.
let always = stack
    .resolve_build(&stack.find_build("qwen3-4b-thinking-2507").unwrap())
    .unwrap();
let err = always.presets.bool_member(&thinking, false).unwrap_err();
assert!(err.message().contains("fixed at `thinking`"), "{err}");
```

- `select(base, &selection)` resolves a document: the caller's `base`, the set's `common` patch, each
  applied preset in order (each axis's default unless a member of it is selected, the `default`
  list, then the selected), and the selection's final `patch`.
- `check_selection(&selection)` is the same check without the document: unknown presets, two
  members of one axis, a member the build doesn't offer.
- `applied(&selection)` lists the presets `select` would apply, in order.

## Choosing builds

A tool chooses with a `SelectionContext` (its defaults and named selections), the presets it will
apply, and a `SelectRequest` (names, then stages). `PresetSelection::prefix_stage` turns the presets into the
first stage, which keeps only the builds that can take them.

```rust
use bunsen::data::catalog::{
    testing::fixtures,
    presets::PresetSelection,
    select::{
        choose::{
            SelectRequest,
            SelectionContext,
        },
        query::Stage,
        state::{
            SelectEnv,
            StageOrigin,
        },
    },
};
use serde_json::json;

let stack = fixtures::example_stack().unwrap();
let env = SelectEnv::new(&stack);
let context = SelectionContext {
    defaults: serde_saphyr::from_str("[{keep: instruct}]").unwrap(),
    named: Vec::new(),
};

// `--off thinking`: the member `no-thinking`, read from the axis's declaration.
let off = stack.bool_axis_member("thinking", false).unwrap();
let presets = PresetSelection::of([off.as_str()]);
let prefix = || presets.prefix_stage(vec!["--off thinking".into()]);

// Every Qwen3 build that can answer without thinking, largest first.
let request = SelectRequest::default().name("qwen3").stage(
    serde_saphyr::from_str::<Stage>("{order: {desc: parameters}}").unwrap(),
    StageOrigin::Flag("--desc parameters".into()),
);
let run = context.rank(&env, None, prefix(), &request).unwrap();
let leaves: Vec<&str> = run.table.names().iter().map(|n| n.leaf()).collect();
assert_eq!(leaves, ["qwen3-0.6b"]);

// Choosing takes the first; the caller applies the presets.
let (build, _) = context.choose(&env, None, prefix(), &request).unwrap();
let applied = build.build.presets.select(json!({}), &presets).unwrap();
assert_eq!(applied.document["chat"]["enable_thinking"], json!(false));

// One build named alone skips the defaults; one the presets can't apply to is an error.
let named = SelectRequest::default().name("qwen3-4b-thinking-2507");
let err = context.rank(&env, None, prefix(), &named).unwrap_err();
assert!(err.message().contains("was named, but can't be chosen"), "{err}");
```

### `compose`, `rank` and `choose`

| call | does |
|---|---|
| `compose(env, prefix, request, choosing)` | the `ComposedQuery`: the stages, each one's `StageOrigin`, and the build named alone, if any |
| `run_composed(env, universe, composed)` | runs it, traced, over every build (or `universe`) |
| `rank(env, universe, prefix, request)` | `compose` without the limit, then `run_composed`: every row of the result |
| `choose(env, universe, prefix, request)` | `compose` with `limit: 1`: the first build, resolved, and the run; `SelectRun::empty_error` when none is left |

The composed pipeline is a concatenation; nothing is merged:

1. **The prefix**, when the tool applies presets: `keep: {$presets: [..]}`.
2. **The defaults**, unless the request's only name is one build.
3. **The request's names:** a named selection's name splices its stages in (`use`); the other
   names are one `from` stage.
4. **The request's stages**, each `use` spliced in place.
5. **The tail:** `order: {desc: $weight}` when nothing orders, and `limit: 1` when choosing.

An `unset: L` anywhere in the request (or in a named selection) removes the earlier stage
labeled `L`, a default's among them.

A `SelectRun` is the result `table` and its `trace`: one `StageTrace` per stage (its operation,
origin, how many rows it removed, and the weights a `weigh` committed), and every `DroppedRow`,
with the stage and why.

### Derived keys

A derive step adds tags the catalog doesn't hold. A query reads a derived key `k` as the `$`
word `$k`, so it can't collide with a catalog name. `SelectEnv::with_derive` refuses a key that
is a `$` word the language defines.

```rust
use std::collections::BTreeMap;

use bunsen::data::catalog::{
    document::EntryKind,
    testing::fixtures,
    resolve::ResolvedBuild,
    select::{
        query::SelectQuery,
        state::{
            DeriveEach,
            DeriveTags,
            DerivedKey,
            SelectEnv,
            SelectTable,
        },
    },
};
use serde_json::{Value, json};

let stack = fixtures::example_stack().unwrap();
let gigabytes = DeriveEach {
    keys: vec![DerivedKey { name: "gigabytes".into(), description: "At bf16.".into() }],
    tags: |b: &ResolvedBuild| {
        let mut tags = BTreeMap::new();
        if let Some(p) = b.tag("parameters").and_then(Value::as_f64) {
            tags.insert("gigabytes".to_string(), json!(p * 2.0 / 1e9));
        }
        tags
    },
};
let steps: Vec<&dyn DeriveTags> = vec![&gigabytes];
let env = SelectEnv::with_derive(&stack, steps).unwrap();
let query = SelectQuery::from_yaml(
    "{kind: build, run: [{keep: {$gigabytes: {le: 2}}}, {order: {asc: $gigabytes}}]}",
)
.unwrap();
let table = query
    .compile(&env)
    .unwrap()
    .run(&env, SelectTable::universe(&env, EntryKind::Build))
    .unwrap();
assert_eq!(table.names()[0].leaf(), "qwen3-0.6b");
```

## The select language

A query names one kind, then a list of stages run in order:

```yaml
kind: build              # required, first
floor: 0.001             # optional: the least weight a row keeps between stages
run:
  - from: [qwen3, whisper]
  - keep: {instruct: true, thinking: false, parameters: {le: 8.9e9}}
  - weigh: {by: [{when: {language: en}, else: 0.5}]}
  - order: [{desc: $weight}, {desc: parameters}, {asc: $name}]
  - limit: 1
```

**No string is ever parsed.** A string is a name (a reference: `qwen3`, `a/b`, `/root`), a `$`
word, or a literal value in a value position. A map is an operator from a closed vocabulary, or a
test keyed by a name or a `$` word. **Wherever a catalog name can appear, anything that isn't one
starts with `$`.** A `$` word can never be a name, so nothing is reserved.

| `$` word | is |
|---|---|
| `$any`, `$all`, `$not` | the predicate operators |
| `$weight` | the row's weight at that point in the pipeline |
| `$name` | the build's full name |
| `$presets` | can take these presets together |
| `$released` | the release time the build joined its release group with |
| `$license`, `$origin` | the build's fields |
| `$parent` | the naming scope, exactly (a bare name tests membership by closure) |
| `$template_class` | the direct class (a bare class name tests the whole chain) |
| `$contract` | the build's contract, by its name in `$contracts`; `eq` also matches the contracts nested in it, its variants |
| `$k` | a derived key `k` |

Words where no names appear stay bare: stage names, value-test words and weighing words.

### Stages

| stage | argument | does |
|---|---|---|
| `from` | a name or a list of names | keeps the rows in any of them |
| `keep` | a predicate | keeps the rows that satisfy it |
| `drop` | a predicate | `keep: {$not: P}`: `drop: [a, b]` drops the rows in both, `drop: {$any: [a, b]}` either |
| `weigh` | `{by: [..], floor: f}` | updates each row's weight |
| `order` | a sort key or a list of them | sorts, stably |
| `limit` | an integer, 1 or more | keeps the first N |
| `per` | `{group: G, run: [..]}` | partitions the rows, runs `run` on each part, and concatenates the parts |
| `use` | a name | splices in a named selection's stages, when the query is composed |
| `unset` | a label | removes the earlier stage with that label, when the query is composed |

A stage may carry a label, the one key allowed beside its operation: `{keep: instruct, as: tuned}`.
A later `unset: tuned` removes it, so a request can drop a hard default. An `unset` of a label no
earlier stage has, or two stages with one label, is an error.

`per`'s `group` is a facet (for builds: a part per group of it) or a list of names (a part per
name; a row goes in the first it is in). The parts come out in the order of their first row, and
the rows in no group form one more part, last. Each part runs `run` on its own:

```yaml
- per:
    group: family
    run:
      - order: [{desc: parameters}, {asc: $name}]
      - limit: 1
# the largest build of each family: large-v1, qwen3-4b-thinking-2507
```

There is no cutoff stage: a cutoff is `keep: {$weight: {ge: W}}`, at the position the query
chooses.

### Predicates

| written | means |
|---|---|
| `qwen3`, `hybrid`, `qwen3-0.6b` | in a group (by closure), a template class (by chain), a build (itself) |
| `[a, b, ..]` | all of them |
| `{$any: [..]}`, `{$all: [..]}`, `{$not: P}` | the operators |
| `{NAME: true}` / `{NAME: false}` | in / not in the set a name denotes |
| `thinking`, `{thinking: true}` / `{thinking: false}` | a bool axis: it offers the on / the off member |
| `{thinking: switch}` | the axis's implied tag: `always`, `switch` or `never` |
| `{task: translate}`, `{task: {has_any: [..]}}` | a categorical axis: what its use offers |
| `instruct`, `{TAG: VALUE_TEST}` | a bool tag is `true`; a tag's value |
| `{family: qwen3}` | a facet: the build's group in it |
| `{$presets: [P, ..]}` | it can take those presets together |
| `{$WORD: VALUE_TEST}` | a field, `$weight` or a derived key |
| a map with several keys | all of its entries |

**Value tests**, typed by the tag's declaration; a value that doesn't fit is an error:

| written | for | means |
|---|---|---|
| `v` | any | equals; for a set-valued tag, contains |
| `{eq: v}`, `{ne: v}` | single-valued | equals / doesn't |
| `{lt: n}`, `{le: n}`, `{gt: n}`, `{ge: n}` | counts, times, `$weight`, derived keys | compares; several make a range, `{ge: 1e9, le: 4e9}` |
| `{in: [..]}` | single-valued | is one of these |
| `{has: v}`, `{has_all: [..]}`, `{has_any: [..]}` | set-valued (`languages`, `text_list`, categorical offers) | contains |
| `{exists: true}` | any | has a value |

A build without a value fails every test but `{exists: false}`. A `languages` tag contains a
language by RFC 4647 filtering: `en` contains `en-US`, not the other way round.

### Weighing

Every row starts at weight 1, and only `weigh` changes it. A block applies its `by` entries in
order, as signed arithmetic, commits the result clipped to 0 or more, and drops the row below its
own `floor`. The query's `floor` (1e-9 unless set; `floor: 0` keeps everything) applies after each
block: a row below it is dropped there, even if a later block would raise it again. An update that
should recover a row goes in the same block.

| entry | does to the weight |
|---|---|
| `{when: P, else: w, then: v}` | × `v` (default 1) if the row satisfies P, else × `w` (default 0) |
| `{match: {TAG: L}, truncated: t, else: w}` | × 1 when `L` filters to one of the tag's languages, × `t` (default 1) when only a truncation of `L` does, else × `w` (default 0) |
| `{release: latest, step: s, min: m}` | × 1 for the newest of its release group in the catalog, `s` (default 0.05) less per newer release, never below `m` (default 0); × 1 in no release group |
| `{mul: k}`, `{add: k}`, `{clip: [a, b]}` | × k; + k; clamps |

Weights aren't bounded above, and nothing renormalizes.

```yaml
- from: whisper
- weigh: {by: [{release: latest, step: 0.25}]}
# large-v1 (0.5), large-v2 (0.75), large-v3 (1), large-v3-turbo (1, in no release)
- keep: {$weight: {ge: 0.6}}
# large-v2, large-v3, large-v3-turbo
```

### Kinds

| kind | name tests | tags, axis tests, `$presets` | `$` fields |
|---|---|---|---|
| `build` | its groups (by closure), its template-class chain, itself | its own, its chain's, the implied ones, derived keys | `$released`, `$license`, `$origin`, `$template_class`, `$contract` |
| `template_class` | the groups it joins through its chain (by closure), its base chain, itself | its chain's, and its folded axis uses and presets | |
| `namespace`, `release` | the groups in its closure, itself | none | |
| `tag`, `axis`, `facet`, `resource`, `alias`, `type`, `contract` | the scopes that enclose it, itself | none | `$format`, `$dtype` (a resource's) |

`$weight`, `$name`, `$parent`, `weigh` (`when`, `mul`, `add`, `clip`), `order` and `limit` apply to
every kind; `match` to builds and template classes, `release` to builds. A test the kind doesn't
admit is an error when the query compiles. Choosing takes a build; a query of another kind is
ranked.

```yaml
kind: resource
run:
  - keep: qwen3-0.6b              # the resources in the build's scope
  - keep: {$format: json}
# qwen/qwen3/qwen3-0.6b/config
```

### `order` and `limit`

A sort key is `K` (ascending), `{asc: K}` or `{desc: K}`, with an optional `missing: first` (the
default puts rows without a value last). The keys are `$weight`, `$name`, `$released`, count tags
and derived keys. The sort is stable, so a trailing `{asc: $name}` makes the order total. `limit:
N` keeps the first N.

### Recipes

```yaml
# The largest instruction-tuned Qwen3 that can answer without thinking.
- from: qwen3
- keep: {instruct: true, thinking: false}
- order: {desc: parameters}
# qwen3-0.6b

# English speech, newest release, without the pruned turbo build.
- keep: {$contract: whisper-asr}
- drop: large-v3-turbo
- weigh: {by: [{when: {language: en}}, {release: latest}]}
- order: {desc: $weight}
# large-v3 (1), large-v2 (0.95), large-v1 (0.9)

# Prefer timestamps, but take any Whisper build.
- from: whisper
- weigh: {by: [{when: timestamps, else: 0.5}]}
- order: {desc: $weight}
# large-v3 (1), then large-v1, large-v2, large-v3-turbo (0.5 each)

# The two smallest builds that can think.
- keep: thinking
- order: parameters
- limit: 2
# qwen3-0.6b, qwen3-4b-thinking-2507

# British English, accepting builds that list only `en`, and none that merely wildcard it.
- weigh: {by: [{match: {language: en-GB}, truncated: 0.8, else: 0.4}]}
- keep: {$weight: {ge: 0.5}}
- order: {desc: $weight}
# the Whisper builds (0.8 each); Qwen3's `"*"` weighs 0.4, below the cut
```

## The CLI

```sh
bunsen-tool catalog select <names> <flags>
bunsen-tool catalog --catalog local.yml select <names> <flags>
```

`bunsen-tool catalog` runs over the built-in catalog, and the dev crate's `pretrained-catalog` runs
the same commands over the example catalogs, without the model kits; `--catalog` imports an
extension over either. It stands in for a tool that chooses builds. Each flag is one stage, in command-line order,
and each flag value is one YAML particle. `--on`, `--off` and `--preset` are the exception: they
are the presets the tool applies, and the prefix that keeps only the builds that can take them,
wherever they sit on the command line.

| flag | stage |
|---|---|
| `--kind K` | the query's kind; `build` by default |
| bare names | one `from: [..]`; a named selection's name is a `use` |
| `--keep P`, `--drop P` | that stage; P is a name or a flow map |
| `--lt/--le/--gt/--ge/--eq/--ne KEY V` | `keep: {KEY: {le: V}}`, and so on |
| `--has TAG V` | `keep: {TAG: {has: V}}` |
| `--weigh E` | `weigh: {by: [E]}`; `--weigh-block '{by: [..], floor: f}'` for a whole block |
| `--cutoff W` | `keep: {$weight: {ge: W}}` |
| `--asc K`, `--desc K` | one sort key; consecutive ones join one `order` stage |
| `--limit N`, `--use NAME`, `--unset LABEL` | that stage |
| `--per GROUP` … `--end` | a `per` stage; the flags between are its `run` |
| `--pipeline FILE_OR_FLOW` | a whole list of stages, spliced in |
| `--floor F` | the query's floor |
| `--on X`, `--off X`, `--preset P` | the presets applied, and the prefix |
| `--defaults FILE_OR_FLOW` | the context's defaults: a list of stages |
| `--rank` | also prints every row a stage removed, with why |

A bare name or a number goes as it is; anything else goes in single quotes (a flow map, a `$`
word).

```sh
pretrained-catalog select qwen3 --off thinking --keep instruct --desc parameters --limit 1
pretrained-catalog select whisper --weigh '{release: latest}' --cutoff 0.9 --rank
```

`select` prints YAML: the composed `query`, `why` (each stage: its operation, origin, how many
rows it removed, and a `weigh`'s weights), `dropped` (with `--rank`), the `presets` applied, and
the `results`: each build resolved with its weight, or, for another kind, each entry's name,
kind and weight.

## Lower layers: a query by hand

A `SelectQuery` compiles against a `SelectEnv` (which checks every name and test against the
stack) and runs on a `SelectTable`, traced or not. Nothing composes it: no defaults, no prefix,
no tail.

```rust
use bunsen::data::catalog::{
    document::EntryKind,
    testing::fixtures,
    select::{
        query::SelectQuery,
        state::{
            SelectEnv,
            SelectTable,
        },
    },
};

let stack = fixtures::example_stack().unwrap();
let env = SelectEnv::new(&stack);
let query = SelectQuery::from_yaml(
    r#"
kind: build
run:
  - from: whisper
  - weigh: {by: [{release: latest, step: 0.25}]}
  - keep: {$weight: {ge: 0.6}}
  - order: [{desc: $weight}, {asc: $name}]
"#,
)
.unwrap();
let compiled = query.compile(&env).unwrap();
let run = compiled
    .run_traced(&env, SelectTable::universe(&env, EntryKind::Build))
    .unwrap();
let leaves: Vec<&str> = run.table.names().iter().map(|n| n.leaf()).collect();
assert_eq!(leaves, ["large-v3", "large-v3-turbo", "large-v2"]);
// The trace says where each row went, and why.
let v1 = run
    .trace
    .dropped
    .iter()
    .find(|d| d.entry.path.leaf() == "large-v1")
    .unwrap();
assert_eq!((v1.stage, v1.weight), (2, 0.5));
```

`select::typed` holds `match_language`, the RFC 4647 matcher that the tests and `match` share.

## Errors

Every failure is a `BunsenError`. A catalog problem carries a `CatalogProblem` as its cause: the
`CatalogRule` it breaks, a message, and, where known, the entry and the catalog it was found in.
An import that finds several problems returns one error whose cause is a `Multiple` of them.
`CatalogErrorExt` reads either: `problems()`, `has(rule)`, `mentions(text)`, `rule()`,
`problem_message()` and `problem_lines()`. A `Lookup` rule is a
[`Lookup`](crate::errors::BunsenErrorKind::Lookup) error; every other rule is a
[`Policy`](crate::errors::BunsenErrorKind::Policy) error: a catalog or a request read from
outside the program that breaks it.

| rule | raised by |
|---|---|
| `Parse`, `Name`, `Structure`, `Conflict`, `Reference`, `Merge`, `Facet`, `Contract`, `Tag`, `Preset`, `Release`, `Dependency` | importing a catalog: the document's rules |
| `Lookup` | `find`, `find_build`: a name that matches nothing, or several entries |
| `Selection` | a query (a stage or key of the wrong shape, a name that resolves to nothing, a value that doesn't fit its declaration), a preset selection a build can't take, an axis flag on something that isn't a bool axis, a build named alone that the run removed, and an empty result |

Selection messages name the stage and the key at fault: ``"stage 1 (`keep`): `instruct`: "maybe"
is not `true` or `false`"``, ``"stage 0 (`from`): `qwen3-1.7b`: nothing matches `qwen3-1.7b`"``,
``"stage 2 (`limit`): `limit` is a count, 1 or more"``. An empty result names the stages that
removed rows: ``"no build is left to choose: stage 0 (`keep`, prefix: --off thinking) dropped
5"``.