# bookclerk_resolve

Sans-IO resolver for the library data model.

Storefronts describe what they sell; the host decides identity. This
crate maps one store listing to an FRBR edition, expression and work
([library data model ADR](https://github.com/Bookclerk/bookclerk/blob/main/docs/adr/library-data-model.md)):

1. [`Listing::from_draft`](/docs/internals/crates/bookclerk_resolve/listing/index.md#listingfrom_draft) validates and normalises what a plugin
   reported. It is the untrusted-input boundary.
2. The caller reads a [`Snapshot`](/docs/internals/crates/bookclerk_resolve/model/index.md#snapshot) of the stored rows that bear on the
   listing (the store from SQL, [`memory::MemoryCatalog`](/docs/internals/crates/bookclerk_resolve/memory/index.md#memorycatalog) from memory).
3. [`resolve`](#resolve) returns a [`Plan`]: the rows to insert, the identifiers to
   attach, the conflicts to record for an Administrator and the events
   to publish. The caller applies it as one atomic batch.

Nothing here performs I/O, so the fuzz target (`library_resolve`), the
replay test and the store all drive the same code.

| Item | Kind | Summary |
| --- | --- | --- |
| [`IdSource`](#idsource) | trait | Mints ids for new rows; the store uses UUIDs, tests use counters. |
| [`EntityKind`](#entitykind) | enum | The kind of row a new id is minted for. |
| [`resolve`](#resolve) | function | Resolves one listing against a snapshot of the stored rows. |
| [`resolve_catalog`](#resolve_catalog) | function | Resolves a catalog listing (a title a store sells that nobody in the library holds) against a snapshot of the stored rows. |

## Re-exports

- [`identifiers::normalize_identifier`](/docs/internals/crates/bookclerk_resolve/identifiers/index.md#normalize_identifier)
- [`identifiers::IdentifierKey`](/docs/internals/crates/bookclerk_resolve/identifiers/index.md#identifierkey)
- [`kinds::Abridgement`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#abridgement)
- [`kinds::CreditRole`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#creditrole)
- [`kinds::Entitlement`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#entitlement)
- [`kinds::ExpressionKind`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#expressionkind)
- [`kinds::IdentifierScheme`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#identifierscheme)
- [`kinds::Level`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#level)
- [`kinds::MediaKind`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#mediakind)
- [`kinds::Strength`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#strength)
- [`kinds::WorkKind`](/docs/internals/crates/bookclerk_resolve/kinds/index.md#workkind)
- [`labels::clean_series_name`](/docs/internals/crates/bookclerk_resolve/labels/index.md#clean_series_name)
- [`labels::series_key`](/docs/internals/crates/bookclerk_resolve/labels/index.md#series_key)
- [`labels::strip_edition_marker`](/docs/internals/crates/bookclerk_resolve/labels/index.md#strip_edition_marker)
- [`language::normalize_language`](/docs/internals/crates/bookclerk_resolve/language/index.md#normalize_language)
- [`listing::stored_marketplace`](/docs/internals/crates/bookclerk_resolve/listing/index.md#stored_marketplace)
- [`listing::stored_product_id`](/docs/internals/crates/bookclerk_resolve/listing/index.md#stored_product_id)
- [`listing::work_match_key`](/docs/internals/crates/bookclerk_resolve/listing/index.md#work_match_key)
- [`listing::Credit`](/docs/internals/crates/bookclerk_resolve/listing/index.md#credit)
- [`listing::Holder`](/docs/internals/crates/bookclerk_resolve/listing/index.md#holder)
- [`listing::HoldingDraft`](/docs/internals/crates/bookclerk_resolve/listing/index.md#holdingdraft)
- [`listing::Listing`](/docs/internals/crates/bookclerk_resolve/listing/index.md#listing)
- [`listing::ListingDraft`](/docs/internals/crates/bookclerk_resolve/listing/index.md#listingdraft)
- [`listing::ListingError`](/docs/internals/crates/bookclerk_resolve/listing/index.md#listingerror)
- [`listing::ListingKey`](/docs/internals/crates/bookclerk_resolve/listing/index.md#listingkey)
- [`listing::SeriesEntry`](/docs/internals/crates/bookclerk_resolve/listing/index.md#seriesentry)
- [`model::Conflict`](/docs/internals/crates/bookclerk_resolve/model/index.md#conflict)
- [`model::CreditWrite`](/docs/internals/crates/bookclerk_resolve/model/index.md#creditwrite)
- [`model::EditionIdentifierRow`](/docs/internals/crates/bookclerk_resolve/model/index.md#editionidentifierrow)
- [`model::EditionRow`](/docs/internals/crates/bookclerk_resolve/model/index.md#editionrow)
- [`model::Event`](/docs/internals/crates/bookclerk_resolve/model/index.md#event)
- [`model::ExpressionRow`](/docs/internals/crates/bookclerk_resolve/model/index.md#expressionrow)
- [`model::HoldingRow`](/docs/internals/crates/bookclerk_resolve/model/index.md#holdingrow)
- [`model::LinkReason`](/docs/internals/crates/bookclerk_resolve/model/index.md#linkreason)
- [`model::ListingRow`](/docs/internals/crates/bookclerk_resolve/model/index.md#listingrow)
- [`model::Override`](/docs/internals/crates/bookclerk_resolve/model/index.md#override)
- [`model::Plan`](/docs/internals/crates/bookclerk_resolve/model/index.md#plan)
- [`model::SeriesWrite`](/docs/internals/crates/bookclerk_resolve/model/index.md#serieswrite)
- [`model::Snapshot`](/docs/internals/crates/bookclerk_resolve/model/index.md#snapshot)
- [`model::WorkIdentifierRow`](/docs/internals/crates/bookclerk_resolve/model/index.md#workidentifierrow)
- [`model::WorkMatchKey`](/docs/internals/crates/bookclerk_resolve/model/index.md#workmatchkey)
- [`model::WorkParent`](/docs/internals/crates/bookclerk_resolve/model/index.md#workparent)
- [`model::WorkReason`](/docs/internals/crates/bookclerk_resolve/model/index.md#workreason)
- [`model::WorkRow`](/docs/internals/crates/bookclerk_resolve/model/index.md#workrow)

## Modules

- [`fuzzing`](/docs/internals/crates/bookclerk_resolve/fuzzing/index.md): Fuzz input decoding and the oracle the `library_resolve` target checks.
- [`identifiers`](/docs/internals/crates/bookclerk_resolve/identifiers/index.md): External identifiers: normalisation and the key they are stored under.
- [`kinds`](/docs/internals/crates/bookclerk_resolve/kinds/index.md): Closed vocabularies of the library data model.
- [`labels`](/docs/internals/crates/bookclerk_resolve/labels/index.md): Store labels that name the same thing in different spellings.
- [`language`](/docs/internals/crates/bookclerk_resolve/language/index.md): Language codes: one spelling for the many ways stores write a language.
- [`listing`](/docs/internals/crates/bookclerk_resolve/listing/index.md): The validated listing a storefront reports, and who holds it.
- [`memory`](/docs/internals/crates/bookclerk_resolve/memory/index.md): An in-memory library that reads snapshots and applies plans.
- [`model`](/docs/internals/crates/bookclerk_resolve/model/index.md): Stored rows the resolver reads, the snapshot of them it is given, and the plan of writes it returns.
- [`names`](/docs/internals/crates/bookclerk_resolve/names/index.md): Splitting a store's display string of contributor names.
- [`normalize`](/docs/internals/crates/bookclerk_resolve/normalize/index.md): Title and author cleaning for compares.

## Traits

### IdSource

```rust
pub trait IdSource {
    fn next_id(&mut self, kind: EntityKind) -> String;
    fn edition_id(&mut self, key: &ListingKey) -> String;
}
```

Mints ids for new rows; the store uses UUIDs, tests use counters.

#### IdSource::next_id

```rust
fn next_id(&mut self, kind: EntityKind) -> String
```

A fresh id, never returned before, for a new row of `kind`.

#### IdSource::edition_id

```rust
fn edition_id(&mut self, key: &ListingKey) -> String
```

The id for a new edition first seen through the listing `key`.

The store derives it from `key`, so every node that resolves the same
listing first mints the same edition id. The resolver mints an
edition only for a listing with no stored edition, but that
listing's first edition can outlive it (holding other listings), so
a caller deriving ids must check the id is free; the store mints a
random one when it is not. The default is [`IdSource::next_id`](#idsourcenext_id).

Implemented by: `CounterIds`

## Enums

### EntityKind

```rust
pub enum EntityKind {
    Work,
    Expression,
    Edition,
    Listing,
}
```

The kind of row a new id is minted for.

**Variants**

- `Work`: A work.
- `Expression`: An expression.
- `Edition`: An edition.
- `Listing`: A store listing.

Implements: `Clone`, `Copy`, `Debug`, `Eq`, `PartialEq`

## Functions

### resolve

```rust
pub fn resolve(
    listing: &Listing,
    holding: &HoldingDraft,
    snapshot: &Snapshot,
    ids: &mut dyn IdSource,
) -> Plan
```

Resolves one listing against a snapshot of the stored rows.

#### Arguments

* `listing` - The validated listing.
* `holding` - Who holds it and how.
* `snapshot` - The stored rows that bear on it ([`Snapshot`](/docs/internals/crates/bookclerk_resolve/model/index.md#snapshot) states
  what the caller must include).
* `ids` - Mints ids for the rows the plan creates.

#### Returns

The plan of writes. Resolving the same listing again after applying
the plan returns a plan for which [`Plan::is_noop`](/docs/internals/crates/bookclerk_resolve/model/index.md#planis_noop) holds.

### resolve_catalog

```rust
pub fn resolve_catalog(
    listing: &Listing,
    snapshot: &Snapshot,
    ids: &mut dyn IdSource,
) -> Plan
```

Resolves a catalog listing (a title a store sells that nobody in the
library holds) against a snapshot of the stored rows.

The listing reaches a work, an expression and an edition exactly as
[`resolve`](#resolve) would place it, so a later scan of the same product finds
the same rows; the plan carries no holding, so the library does not
hold the edition.

#### Arguments

* `listing` - The validated listing.
* `snapshot` - The stored rows that bear on it.
* `ids` - Mints ids for the rows the plan creates.

#### Returns

The plan of writes, with [`Plan::holding`](/docs/internals/crates/bookclerk_resolve/model/index.md#plan) set to `None`.
