Selecting on inventory-defined fields is not supported when an inventory is attached

[d-chambers]

Once a spool carries an inventory, the fields that inventory defines should be selectable, and today they are not: spool.attach_inventory(inv).select(coupling="cement") raises InvalidSpoolQueryError because the index has no such column. The spec (API/spool.qmd) documents this workflow, so the gap is between the design and the implementation rather than in the design.

Two levels, with quite different mechanics:

Acquisition-level (whole patch). Fields of the acquisition or interrogator — gauge_length, interrogator.model. A patch matches or it does not. Resolution is pure metadata: for each distinct data_source_id and time window in the index, resolve the acquisition, test the predicate, keep or drop the row. No patch data is loaded and len(spool) stays exact.

Channel-level (within a patch). Track fields (coupling.medium), annotation groups (zone), geometry axes (latitude, z), and optical distance. These select a set of channels, which may be disjoint along the fiber, so a matching patch is trimmed and sometimes subdivided. That changes the number of patches, so it cannot be answered from the index alone; it needs a resolution pass over the inventory per row. prune_to_inventory (below) is the natural place for that pass, since it is already the documented one-time metadata cost.

What comes back on the patch. A name used in a select should arrive on the extracted patch, and nothing more: select(coupling="cement") yields patches carrying coupling.medium so the result says why each channel survived, without paying for blanket enrichment. Composed with an explicit Spool.enrich, the patch owes the union of what was asked for.

Related and not yet implemented:

• Spool.prune_to_inventory(inventory=None) — resolve the index against the inventory, drop rows it does not describe (on_missing of raise/warn/drop), and subdivide rows straddling an epoch boundary.
• Lazy attachment: attach_inventory should accept a path and not read it until something needs it, plus an auto-attach from a blessed name in a spool directory. This depends on the authoring-format loader, which does not exist yet.

Spool.select currently adds a note to its error naming the attached inventory and saying this is not supported yet, so the failure at least points somewhere useful.

[d-chambers]

Small item to fold in whenever Spool.enrich is next touched, deliberately not done on its own because it is docstring-only and would re-run CI for nothing.

Patch.enrich composes its parameter documentation from shared fragments:

@compose_docstring(
    conflict_desc=attr_conflict_description, on_missing_desc=on_missing_description
)

Spool.enrich instead paraphrases the same arguments in prose ("attrs, coords, conflicts, ..."), so the two can drift. Everything else about the pair is already shared — Spool.enrich holds arguments and defers to Patch.enrich per extracted patch, with no second implementation, and it derives its accepted parameter names from inspect.signature(dc.Patch.enrich) rather than restating them. The docstring is the only place the two describe the same thing twice.

Spool.select shows the pattern to copy: @compose_docstring(doc=get_docstring(BaseSpool.select)).

[d-chambers]

Policy-vocabulary decisions for this phase, settled in the spec (API/spool.qmd) so they do not get re-litigated.

Do: prune_to_inventory takes on_unresolved, not on_missing. It and Spool.enrich answer the same question — what about a patch the inventory does not describe — so they share the parameter name, and only the actions their verb allows differ:

• Spool.enrich(on_unresolved=...) → "warn" (default) / "raise" / "ignore"; it never removes a patch.
• Spool.prune_to_inventory(on_unresolved=...) → "warn" / "raise" / "drop"; removing rows is the point.

Spelling prune's policy on_missing would collide with Patch.enrich's on_missing, which takes a different vocabulary at a different scope, and would contradict the reason on_unresolved exists at all.

Do not: rename Patch.enrich's on_missing="skip" to "ignore". The two parameters are different kinds of thing. on_unresolved and WARN_LEVELS are a volume axis, whose members take the same action and differ only in whether they announce it. on_missing is a result axis: "raise" fails, "nan" fills a marker, "skip" leaves the name off — three outcomes, not three loudness settings. ignore elsewhere means proceed quietly rather than produce a different result, so reusing it would make one word mean both. raise is the only member that already means the same thing everywhere, and that is the reconciliation available without flattening a real distinction.

conflicts ("keep_first"/"raise"/"drop") stays as is — matching chunking's attr-conflict flag is worth more than internal tidiness.

Open: on_missing="nan" fills NaN for floats but None for strings, so the name misdescribes half the cases it covers. "null" or "missing" would be true across dtypes. Deferred here only because it touches code on a green PR; worth doing whenever Patch.enrich's signature is next opened.

[d-chambers]

Design decisions for this phase, settled in discussion 2026-08-11:

prune_to_inventory is renamed conform_to_inventory, and it is the one eager reconciliation step. Attaching an inventory stays free and makes no promise that the spool matches it; conform_to_inventory(inventory=None, on_unresolved=...) is what makes the spool truthful against the inventory: patches the inventory does not describe are dropped, patches straddling a path-epoch boundary are subdivided (so the row count can grow — "prune" was the wrong word), and a patch straddling an acquisition-epoch boundary raises, naming the file and the boundary, since no valid file spans a configuration change. It resolves every row eagerly, which is exactly why the laziness lives in attach/enrich and the cost lives here. The undescribed-patch scenario should become rare to impossible as the workflow matures, so the implementation should stay simple rather than gold-plate that edge.

Qualified names in select use the existing _coords/_attrs mapping spelling. Dotted names cannot be Python kwargs, and spool select already accepts namespace mappings, so select(_coords={"coupling.coupling_type": "cemented"}) (equivalently **{...}) is the spelling; nothing new is added. Bare track names stay ordinary kwargs (unselect(coupling=None) for undefined coverage). Syntactic sugar can come later — minimum viable implementation first.

An inventory-backed selector silently does not match a patch the inventory does not describe. Select is a filter: a patch with no corresponding acquisition entry has no coupling, geometry, or tracks, so it simply is not selected and is absent from the returned spool — same rule as a patch lacking a queried attr, no warning, no policy knob. This is the one deliberate exception to loud-by-default, because warning here would make composed selects noisy on intentionally partial inventories.

Policy vocabulary unifies in this phase: Patch.enrich's on_missing value "skip" is renamed "ignore", so every policy knob draws from one word set (raise/warn/ignore, plus "null" which is genuinely an action rather than a policy). Nothing is released, so the rename is free here.

[d-chambers]

Remaining decisions for this phase, settled in discussion 2026-08-12. Working plan lives in the implementation worktree (.scratch/phase-3-plan.md).

Three PRs, in dependency order: (a) the inventory names accessor, acquisition-level select, a general Spool.unselect, and the on_missing renames; (b) conform_to_inventory, which owns the row-subdivision machinery; (c) channel-level select/unselect and split_by, reusing (b)'s subdivision along distance.

The names accessor is one Inventory method, split by destination. It returns the names this inventory could contribute to a patch as two groups, attrs and coords, mirroring Patch.enrich and select's _attrs/_coords spelling. The attrs side is introspected from the models so a new field is automatically selectable; the coords side (annotation groups, CRS axis labels) is computed from the instance. The only hand-blessed constant is the track-name → identity-field map, pinned to the model by a test.

Name precedence is per-row: the patch wins, the inventory backfills. A select on a name both sides know uses the index value wherever a row states one and resolves from the inventory only for rows whose value is null. A spool with fully-stated headers never touches the inventory; resolution is cached per distinct (acquisition_key, epoch).

The inventory never writes into the index database. The spool holds a reference, set by attach_inventory; every inventory-derived filter or row rewrite (conform's subdivision, channel-level trims) hits the in-memory contents dataframe of a new spool instance. The SQLite file records only what files state, so swapping inventories can never leave stale derived values behind. The one route by which inventory facts become index facts is the ordinary round trip: enrich, write, rescan.

Subdivision is an eager dataframe rewrite — one source row becomes N rows with disjoint bounds, and extraction already honors per-row bounds — so len and get_contents stay exact with no new extraction machinery.

Bare numeric ranges on geometry axes are read in the CRS's own units, the same "bare means the definition's native units" rule #872 established for stored coordinates.

on_missing="nan" is renamed "null" alongside "skip" → "ignore", resolving the open item above; the marker is NaN only for floats and None for strings, so "null" is the name that is true across dtypes.

The path-segment-override warning proposed in API/spool.qmd is in scope for this phase.

For the record: unselect was never a dascore PR — it has lived in the spec repo's API/spool.qmd since the first spec commit and this phase is its first implementation.

[d-chambers]

Settled 2026-08-12 while reviewing PR (a) (#877): Patch.unselect belongs to PR (c), not to (a).

The question was whether Patch.unselect could simply wrap the patch in a spool and defer to Spool.unselect. It cannot, because the two take disjoint arguments:

• Patch.select is coordinate-only — patch.select(distance=(50, 300)) trims the array, and it accepts no attrs.
• Spool.unselect is attr-only — it deliberately refuses coordinate selectors, since at spool level the complement of a range is a hole in each patch rather than a filter over patches.

A delegating Patch.unselect could therefore accept only attrs and would return a patch-or-nothing rather than a patch — not the complement of Patch.select, and sharing nothing worth sharing (Spool.unselect's body is a few lines of id-set arithmetic over select).

Patch.unselect should instead be the true complement of Patch.select: patch.unselect(distance=(50, 300)) keeps everything outside the range. The property that makes a range complement wrong for a spool — it leaves a hole — is exactly what makes it right for a patch, which can have samples removed.

The sharing runs the other way, which is why it lands in (c): channel-level select/unselect trims patches along the fiber, so it consumes the patch-level operation rather than providing it. Building it in (a) would leave it without a caller until (c) anyway.

[d-chambers]

Implemented and merged. Spool.select resolves inventory-defined names when an inventory is attached — dc.spool(patch).attach_inventory(inv).select(zone="north") trims to the channels the inventory places in that zone, and a selection matching several disjoint runs of fiber comes back as several patches.

Landed across #891 and #897; it stayed open only because dev is not the default branch, so the closes-keyword never fired on merge.