Code reference

Add needs an activated catalogue build (design 6.1 step 3). Without one it says what to run; it never fails with a 500.

Items of one kind by number or name: {items: [...first 100, decorated], count}.

A number matches the Rebrickable number and the BrickLink one (items.find: born key, the catalogue's search index over every linked number, confirmed BrickLink links); words match names by prefix (catalogue.item_fts); a size ("2x4", "x2") filters by the size key of part names (#41); local items (BrickLink-only or unidentified) are searched by name and number.

The identity of an item id (a merged item as the item it was merged into), else None when neither file knows it.

Every colour of the collection (the catalogue's are projected at activation), by name.

The picture source order for a kind: the setting source_priority.pictures (design 6.8), else the default (core.pictures.order).

Rows with an item_id (and optionally color_id, list_id) gain the numbers to show (label, number, also), the best picture, what is owned and wished already and whether a link waits to be checked. A handful of queries for any number of rows.

Rows of a Brickset My Sets CSV: the sets marked owned (Add to Owned or Loose) or wanted (Add to a wishlist), as Number-Variant. An owned count split into new and used becomes a row per condition; the rest has no condition, as in any file. UserNotes is the note.

Rows of a Brickset minifigure CSV: the figures owned loose (QtyOwnedLoose; Loose or Owned) or marked wanted (one each; a wishlist), by Brickset's minifigure number, which is BrickLink's. UserNotes is the note.

Rows of a BrickLink wanted list or inventory (XML: BrickLink numbers and colour numbers), a Rebrickable CSV (Rebrickable numbers and colour ids), a Brickset My Sets CSV (set numbers; where picks its owned or its wanted sets) or Brickset's minifigure CSV (minifigure numbers: the loose ones or the wanted ones). Nothing is looked up here.

What a row for an unknown number offers (design 6.5): add it as unidentified (always), fetch a set from Rebrickable (a set, with a key). help says what would help when there is no way to get the real item.

Review proposal for input rows: {items, unresolved}. Writes nothing.

The Add review's Part list picker for a set (design 4.3): None unless there is a choice, else {'options': [{'key', 'label', 'note'}], 'preselected': key} in the order of the design's preselection (copies.part_list_choices).

True when no picture is known for a part row in its colour (design 6.8): the review warns before confirming.

The review rows as the person edited them, validated against the proposal (identity never comes from the edit).

The saved receipts of a batch, in review order, each with the event_id that undoes it.

Write the reviewed rows, one transaction each, and return their receipts (a row already saved under this batch returns its saved receipt, so a lost response never doubles a row). A row that fails stops the batch; rows before it stay saved. photo is the picture a photo-mode Add recognised; it is kept as the new item's own photo only with keep_photo.

A fetch job of an Add receipt is done (or finally failed) and the receipt has not been settled yet: the next drain settles it.

Create what the receipts of a finished rebrickable_set job asked for, once each: the quantity of copies of the fetched set (with the latest Rebrickable list, the same preselection as any Add), or its wish, and the set's own pipeline job. Each is one add:fetched event, undoable like the receipt's rows; rows that cannot be made are recorded as add:fetch_failed and not tried again. A job that failed leaves its receipt with nothing to create (the job view says so; Retry queues the job again and a later run settles it). Returns the number of receipts settled.

What became of the Add row that fetched this job's set, for the Add page: {'state', 'message', 'copies'}. state is added (rows made), waiting (the job is not done), failed (the job failed: nothing was added), refused (the fetch worked but the rows could not be made) or unsettled (done, rows follow with the next drain).

Undo every row of a batch that is not undone yet, last row first, all or none. Returns the number of rows undone.

Readable text for the shared catalogue colour chip.

(via, actor) for an event written now: the request's audit origin, else the app.

Start a new operation in this context (a web request, a CLI command, a worker pass) and return its key.

Every event written after this call shares the key (event.operation_key, design 5.2). Call it once at the entry point; end_operation() clears it. Code with no operation (a test, a script) writes events with a NULL key.

begin_operation for the length of a block; the previous key is restored on exit.

The 3.3-style entity string as the 4.0 pair: split at the first colon (copy:<id> -> ('copy', '')); no colon, or nothing after it, gives an entity_id of None.

Write one event on the 4.0 event table. The signature is the 3.3 one; entity is split into entity_kind and entity_id (split_entity), operation_key is the current operation's. old/new are stored by store4.audit.value_text, the one rule every event writer uses (None as NULL, strings as they are, dicts and lists as sorted JSON).

Add, rename or archive a value; returns the event id of the change (Undo takes it back).

The freshness rules a new collection starts with (3.3's: prices 30 days, metadata 365, pictures never). Only into an empty table.

What a fresh collection starts with (user journey § 1): the freshness rules, the three system status flags and the database/setup event, in one transaction. Only on a fresh file (no freshness rules yet); returns whether it seeded. A flag of that name already live (from an import) is kept as it is.

The collection file at path, created and seeded when missing (an existing one keeps its own). It opens without a catalogue: onboarding builds the catalogue next (design 6.1) and brickwork setup says where it goes.

The source order per step as the pipeline uses it: the stored source_priority where it names the step, else design 6.8's default.

PATCH /settings (#47): any subset of the whitelisted settings, in one transaction.

freshness: [{source, kind, max_age_days}] (as GET /settings returns it); import_order: {item kind: [the six steps]}; repair: {shipping, fees, min_order, use_loose_stock}; prefer_bricklink_inventory: true or false (new copies take BrickLink's part list, design 4.4); candidate_sets_common_max: a whole number of 25 or more (Lot Detective ignores lines held by more sets than this, #200; default 300).

Save the retail country, the source order and the freshness rules from the Settings page; returns the event id (None when nothing differs from what is stored). Refused whole on a value that does not fit.

The held or wanted (item, colour, condition) whose market price is not fresh from some enabled source of its kind's order.

One row per line the collection holds (a set copy, loose stock, a wish) with item_id, color_id, condition (words; None for "any"), name and, for display, the BrickLink item_type letter and item_no. Fresh means a successful, unvoided sold or stock observation younger than the source's prices freshness rule (7 days when there is none).

The id of an item's pipeline job that has not finished (queued, running or waiting for a budget), else None.

Queue steps for each item of rows (dicts with item_id) that has no unfinished pipeline job; returns the job ids. A bulk action: the jobs are one batch (#127), shown as one row in Jobs, cancelled together, and overtaken by interactive work.

Queue the identity step for booklets without a PDF. A PDF belongs to a set, and a booklet shares the files of the set with its number (collection.instruction_files). The identity step is local in 4.0 and the pipeline has no instruction-PDF step, so this checks the item's number only; it never downloads a PDF. Returns (queued job ids, skipped items: the ones with no number).

The newest jobs, newest first, each with its steps and a heading (the Jobs list): pipeline jobs and the two fetch kinds. count_jobs says how many there are in all. With batches=False the jobs of a bulk action are left out: Jobs shows each batch as one row (#127, pipeline.batches).

The collection counted by completeness, theme, storage and purchase place (live copies), and spent against retail.

The database check: SQLite's integrity and foreign-key checks of the collection (and of the attached catalogue, which is a file of its own), and the rows of every table of the collection.

check plus the cross-file checks of the pair (store4.crosscheck): what brickwork check and the Database page run. API v2's /database/check stays check, so its response keeps its shape.

The stored result of the last explicit database check, or None. Never runs a check.

Run the full check, keep its result with a date (setting maintenance:database_check), and audit the run (one transaction, not undoable).

The set a PDF is attached to, from a BrickLink type letter and a number typed in the form. A PDF belongs to a set (the store allows no other item); a booklet (type I) shares the files of the set with its number, so it names that set.

Install immutable, content-addressed booklets; roll back a new file on failure.

The set a PDF is attached to, from an item id (API v2): a set is its own target, a booklet names the set with its number (as instruction_target); anything else cannot hold a PDF.

instruction_upload for a set already named by its id (the form names it by a typed number).

The Instruction files page: one row per booklet item with the PDFs of the set that has its number (a PDF belongs to a set), its picture, and the PDFs of sets that no booklet item names. Counts canonical booklet identities only: a set-level PDF does not say how many booklets the set has.

Redact strings before serialization, including quoted credential values.

The secret list is read once per call and shared by every nested string.

Saved identifications (newest first) with the candidates each offered, for Identify history. A candidate names its item when it has one (item_id: the number shown is the item's, the picture its cached one); older or foreign rows are read as they are.

The live loose rows the chosen sources hold, each dict(id, item_id, color_id, kind, have, lot_id, storage_id), have being what can be given (workbench.available). With no source chosen: all loose stock. A row in a chosen lot and a chosen storage is one row.

{line key: quantity} of the rows (a figure is a line with colour 0, as in the engine).

The words of a selection: 'Loose stock · 2 lots · 3 storages'.

The Scout of the attached catalogue build (built once per build and process; the engine's key says when it is a new build).

{position: pieces covered} and {position: lines covered in full} of a pile against an index: the engine's min(have, need).

Every set that shares a part line with the pile and passes the filters, best first: [(position, covered, complete lines)] and the count of sets that share a line. Sorted by percent available, then fewest missing pieces, then set id.

{set item id: (figures covered, figures needed)} for the sets that have figures.

The Build Scout answer: dict(catalogue, source, input, total, limit, offset, results); results are the page's sets, each dict(rank, set_item_id, year, theme, parts_available, parts_total, percent, missing_parts, missing_lines, figures_available, figures_required, cost, ...). With detail above 0 each set lists that many of its biggest missing lines (gaps), its missing figures (figure_gaps), its cost and its swaps; cost alone adds the cost. Read-only; ValueError for a refused argument.

The set's part lines the pile does not cover in full: [(key, need, have, missing)], the biggest gap first.

The set's whole-figure lines as [(key, need, have, missing)] (all of them, covered or not).

dict(prices={(item, colour or 0): Decimal}, currency) from price_current for the (item id, colour id or None) pairs: the used price before the new one, a sold average before a stock listing, the newest observation last; a price in another currency than most are is left out.

dict(amount, currency, priced_lines, unpriced_lines) for [(key, quantity)] missing lines against price_map's answer; amount is None when no line is priced.

What a set adds to a row: its biggest missing part lines, its missing figure lines, the cost to complete and its swaps.

One set's full Build Scout numbers for the chosen stock (whether or not it passes a filter), or ValueError for a set that is no candidate.

The BrickLink wanted-list XML of a set's missing parts and figures for the chosen stock, by the exporter the copies use (gaps.export_lines): dict(xml, lines, skipped).

Put the set on the default wishlist, marked WISH_NOTE in the wish's note (by the Add flow, so the receipt is its own and Undo is Add's). Returns dict(event_id, wish_id, already); a set already wished is already and nothing is written.

How a Build it takes from rows (stock_rows): [(stock id, amount)] so that every part line gets min(have, need) and every figure line min(have, need), the largest usable row first and then the lowest id (the Matchmaker's order), and the totals taken.

Build it: one copy of the set, the matching parts and whole figures moved out of the chosen stock into it, the rest recorded as missing on the copy, as one transaction and one undoable event (found_copy.make_copy_in). Returns dict(event_id, copy_id, pieces, figures, missing_parts, missing_figures); a ValueError is a refusal that wrote nothing (a set with no part list or made of sets, nothing in stock for it).

N, the most sets a line may be held by and still count: the stored setting, else 300 (an invalid stored value is the default).

The setting's value as a whole number of at least COMMON_MAX_LOWEST, else ValueError.

The ids of a theme and the themes below it: theme is a catalogue theme id (digits) or a name (case-insensitive). ValueError when unknown.

The part items among items that are printed: the part number has a print suffix (pr and digits, as in 3626bpr0001 or 973pr1234c01) or the catalogue lists the part as the printed child of another part (relationship type P). Derived from what the catalogue holds.

The sentences that say why a set is a candidate. found of total distinctive parts; only_printed and only_other the found parts that exactly one set holds (printed or not); then how much of the set's part lines the lot holds. stickers: the numbers of the sets a sticker in the lot is confirmed for, one reason each.

The engine's flags from the lot's stock flag names: a flag named Sticker (any case) is passed on as sticker, the others are not used.

The ranked candidate sets of a lot, dict(catalogue, input, total, limit, offset, results); ValueError for no such lot or theme.

Each result: rank, set_item_id, score, evidence, coverage, reasons, covered_lines, set_lines, distinctive_found, distinctive_total, distinctive_found_parts and distinctive_missing_parts (up to PARTS_SHOWN each, heaviest first; each line is item_id, color_id, quantity, need, weight, only_in_set, printed) and flags.

{set item id: its number, as1682-1}.

(found, missing): the distinctive lines of a set (held by at most DISTINCTIVE_MAX sets) the lot has and has not, each dict(key, have, need, weight, only_in_set), heaviest first. A common-part drop never touches a distinctive line (N is at least the limit).

The event entity id of a session: the copy, or one figure line inside it.

Sort key of the rows of one kind for an order mode. Largest first is the physical size from the catalogue name and category (part_size.volume; the item's size_key is the sorted dimensions of the same name and cannot tell a plate from a brick), then the larger count, then one colour after another so a part's colours stay together.

Read model of a stored session against the current sequence.

Tokens that are no longer part of the sequence (a line a switch retired, or spare rows before the spare question was answered "Yes") are dropped from the visible order without error, and the cursor keeps pointing at the same remaining step. A required line the session has not met (a switch to another part list added it, design 4.4) joins the end of the walk, so the check can still answer it and finish. Nothing stored is rewritten here; the next save persists the changed form and its receipt keeps the raw old value.

The id of the status flag "Set is checked" (live), or None; with create it is made as a system flag and the creation is audited.

The sequence of a check: the required parts, the whole figures and the spare lines of a copy, all live.

With figure (a copy_figure id) the rows are exactly that figure's required (non-spare) component lines. decorate=False is the write path's light read (names and sizes for ordering, no identity or picture lookups); images=False leaves the pictures out of the decorated rows. Each row: token, kind (part, figure, spare), id, item_id, color_id, quantity, missing, damaged, checked (a figure line has no damaged or checked: its missing is the answer).

What an answer touches, exactly as a receipt keeps it and an Undo compares it.

Derived completeness after an answer (only a copy whose completeness is derived changes).

Check figure parts: one whole figure line's component rows inside this copy.

The chooser: every live copy with its counts and its set-level session. A fixed number of queries, however many copies.

The reply of a save: the changed rows only (the client keeps what it has, pictures included) and the progress counts.

The checker's bounds and update for an answer (design 2.4 invariant 10: each count on its own, 0 to the quantity).

One ordered, idempotent answer and its receipt. figure is a copy_figure id (a figure check inside the copy).

Set counts on lines of a live copy: edits is [(token, fields)], a token p:<copy_part id> or f:<copy_figure id> (a figure line takes missing only) and fields among missing, damaged (each 0 to the line's quantity) and checked. One receipt; the derived completeness follows. A token that is no live line of the copy is NotFound. Returns the event id.

215: Found 1 outside a check session (the set page's missing-part card): the line's missing count drops by one, as Found 1 in the

Set Inspector does, and loose stock stays as it is. One part_check receipt, so Undo takes it back. Returns the event id.

Set or clear the status flag "Set is checked" on a live copy (made when it does not exist yet and is wanted) and let the derived completeness follow. One receipt, also when nothing changes. Returns the event id.

Set counts on the part lines of a live loose minifigure: edits is [(item id, colour id, spare 0 or 1, fields)] with fields among missing, damaged (each 0 to the line's quantity) and checked. One collection receipt over stock_part. Returns the event id.

Every colour the collection knows, by name.

The whole source_priority setting (metadata, market price and picture orders), read once by a screen.

Identity (core.items), colour, picture and the unresolved mark for rows that carry item_id (and color_id).

Adds kind, item_type (the screen letter), number (the Rebrickable born number first, or a local BrickLink-born item's own BrickLink number), number_source, also (the preferred BrickLink number where it differs), number_text (what a screen writes), item_no (= number, '' for an unidentified item), unidentified, unresolved, image, color_name, rgb, ink. Name and year stay what the row has; a row without a name takes the item's. Loaded in a fixed number of queries (loaded is priorities(db) when the caller has it).

The query arguments of an item page for a row: the colour of a part.

{item_id: {key: dict(value, unit, source, fetched_at, alternatives)}}: the best source per key by the metadata priority (a source order per kind word; kinds is {item id: kind} when the caller knows it, else it is read).

Current quotes (price_current over its observation, a voided observation never shows).

One item and colour -> a list; pairs (item id, colour id) rows -> {(item, colour): [quotes]}. used_sold keeps only the used, sold-guide, non-boxed quote: all a list row's price ever reads.

Bulk physical rows (copies, then stock); API archive reads opt in, web defaults stay live-only.

kind is a kind word (None for all); item_id scopes the read to one item: same rows, same labels, same order; stock_only leaves the copies out (the API's stock list). Rows are decorated (decorate), copies are labelled Set N in creation order, flags are on the rows.

One physical row (archived included) shaped exactly like instances(include_archived=True).

Keyed lookups only: no collection-wide scan, so a single read costs the same on any size of store.

{copy id: 'Set N'} for live copies among ids, numbered as instances(db, 'set') numbers them.

The rows of a collection screen: type_letter S, M, P, I, O, G, B or C (wishes: every kind, type_letter is ignored).

A row is an item (and colour): its owned instances grouped, with counts in sets for parts and figures, the used-sold price, and the theme, category and year projected on the item (design 6.3).

Active colours of a part from stock, set lines and wishes, in one read.

Catalogue links of a set: BrickLink by its BrickLink number, Brickset by a confirmed Brickset link (a number of the set itself otherwise). An unidentified set, or one with no BrickLink number, has none.

Required replacements, with whole missing figures covering constituents.

The lines a switch retired, named for the page (design 4.4: kept, excluded from every count, ids still valid): decorated like any line, each with its marks.

The Switch sheet's data (design 4.4): one option per list the copy could move to, each with what the switch would do, read from preview_switch (the lists the real receipt will hold). choose (a choice key) preselects an option; the default is the first that is not the copy's own list. A BrickLink list that is not fetched yet cannot be switched to in place, so it is shown unavailable. Read-only.

Everything the item page shows. colour is a colour id for a part (a part is always held in a colour).

{item id: [files]}: a booklet shares its files with the set of the same number, in both directions (concept: Boxes and instructions).

Figure-wide display facts: its parts across every holder, the sets and the wishes it is in (retired lines excluded).

Retail price and availability (Brickset, #26) for the retail country, or None when the set has none of it.

{currency: dict(per_eur, as_of, source)} including EUR = 1 (the 4.0 exchange_rate table).

Local jump projection: what you own or want that a word of the query names, by name or by either number.

A word matches an item's name, its born (Rebrickable) number, any confirmed BrickLink number, the item id, or the id of a copy or stock line. Sets first, then the exact number, then the number.

The stored columns of a table (a generated column is derived, so it is neither kept in a receipt nor written back).

Write the one event of a request: changes is [(table, rows before, rows after)]. Returns the event id. entity is the event's kind: the workbench and the ledger write theirs under their own names and register the same undoer for them.

Edit or archive collection rows (copies, loose stock, wishes, lots), with their flags, under one receipt. Returns the event id.

data holds the column values to set (an empty string clears a column) and, for one row, flags (the flag ids the row should have among the live flags; links to archived flags are left alone). Stock that ends up with another live row's merge key merges into it (stock.plan_edit), and the receipt keeps both rows.

Refuse, with a clear message, a wish write that would duplicate another live wish of the same list, item and colour.

The live stock rows a save merged other rows into, read from its committed receipt (empty when nothing merged).

Undo a collection receipt (or any event with a registered undoer) by its event id; a second Undo of the same event does nothing.

Keep an own photo of a copy or loose stock row: the file under data/images/own, the row in photo. Undo archives the row; the file stays (it is the user's).

Assign existing loose stock to a new lot, without changing its quantities; rows that then share a merge key merge.

Restore an archived collection or location row under a receipt. A wish or stock row that would now duplicate a live one is refused.

Put an existing item (an unidentified figure, say) on the default wishlist under a receipt. A part needs its colour.

Count destination copies once, excluding loose-figure destinations.

Keep scanner provenance in the row title, leaving user notes visible.

One unsigned defect label for server-rendered and materialized rows.

The market-price source order per kind (setting.source_priority); a kind is a kind word, * is every other.

Source priority first; freshest successful observation within that source.

A set's quote with box (slot 'boxed', any guide): what its price card shows as "With box" and what its max with box is held against (#131). One rule for both.

complete or incomplete for a copy whose completeness is derived, else None: the 4.0 rule is store4.copies's (live, non-spare, non-figure lines; retired lines are no lines).

The catalogue that belongs to the collection at path: catalogue.db in the same folder.

Open the 4.x collection at path (upgraded first when older, unless read_only) with its catalogue attached read-only.

Without the catalogue file require_catalogue decides: True (the default) refuses with the way to get one; False opens the collection alone (setup, and the first-run page that tells the user to get a catalogue).

Upgrade the collection at path in place when it is at an older 4.x version (app start; schema notes 4.1). A no-op when it is current; the refusals read as connect's.

The API v2 contract (M.11a, issue #113); the v2 blueprint serves it and checks its own routes against it, and the MCP adapter reads its tools from it (M.11e).

The BrickLink currency preference of the collection (setting.bricklink_currency), else the documented default EUR.

{currency: dict(per_eur=Decimal, as_of, source)} including EUR = 1.

amount in source as target, with the rate used; None without both rates.

Enter or clear (per_eur None) one rate by hand; one audited write.

Replace the ECB-sourced rates from the daily reference feed. Hand-entered rates stay.

None when nothing is queued, running, waiting or due for a retry; else seconds to the next look (at most 60).

Is there work for the drainer at start-up: an active job, or copies still pending on a finished one (jobs.has_leftovers; the process stopped before settling them). One drain settles what can be settled, then poll_delay lets the worker stop.

At start (the embedded drainer's and brickwork worker's): a catalogue swapped in but not reconciled yet becomes one reconcile job (design 6.2), run by the drain like any other. Returns the job id, or None when nothing is due.

139: a key set in the environment takes effect at a start: the steps that waited for one of the configured sources run again.

One pass of both runners. The fetch jobs go first: a BrickLink or Rebrickable list a pipeline job looks for may have landed. Then the copies a finished Fetch from Rebrickable asked for are made (add.settle_fetches); their pipeline job runs on the next pass.

Drain due jobs, then sleep until the next deadline; return when nothing is pending.

Seam for the embedded drainer's thread; tests replace it.

Looked up at call time, so gevent's patching applies and tests can replace it.

BW_EMBEDDED_WORKER=0 leaves draining to brickwork worker on headless installs.

One drainer per app; a daemon thread is the standalone default.

The active flag is set and cleared under a lock (#68), and the drainer checks for due work once more before it clears the flag, so a job queued while it was stopping is not left waiting.

brickwork worker: drain the queue in this process until nothing is pending (the headless counterpart of the embedded drainer).

The gaps of live copies: [dict(copy_id, item_id, color_id, quantity, condition)], set lines first, then figures, in line order.

The gaps combined per item, colour and condition, each named for BrickLink where it can be: (lines, skipped).

A line is dict(item_id, color_id, condition, quantity, name, color_name, bricklink=(type, number, colour number)); a skipped line is the same with bricklink=None and why (no BrickLink number or no BrickLink colour).

missing_lines for quantities already combined: total is {(item id, colour id, 'N'|'U'): quantity}.

dict(xml, lines, skipped): BrickLink Wanted List XML of the named lines, the lines in it and the ones left out (and why).

The same for quantities already combined (total, see named_lines), e.g. what a repair still has to buy.

A clean JPEG thumbnail (EXIF, ICC and other metadata dropped), or None if unreadable.

(item id or None, why) for a number a provider gave: the born match, else the one item a confirmed BrickLink link names, else the one item the search index finds. Several candidates at the same step place nothing (why says so).

(choices, unresolved) for recognition predictions [dict(item_type 'P'|'M'|'S', item_no, score)].

A choice is the item decorated for a screen (collection.decorate) with score and what you already hold of it (owned_summary). A prediction of another kind than kinds is left out; one that names no item, several items, or an item still to check is listed in unresolved with its reason.

Ask Brickognize about a photo and map the answer: (choices, unresolved). kind (part, minifigure or None) picks the endpoint. The source counts the call against the daily budget and keeps the reply; a failure is a SourceError with no key in it.

Record one result and its thumbnail in the caller's transaction; audited for Undo.

Archive a record (thumbnail kept); Undo restores it.

Undo a stored or archived record by its event id; a second Undo does nothing.

How many items unresolved lists.

{reason: items} over the list (an item with two reasons counts under both).

The list the Unresolved screen shows: one dict per item, ordered by kind and name.

item_id, kind, name, number_text, image, local, reasons, facets (what the screen filters by: the reasons, with status replaced by the status reasons no_candidate, kind_differs, migration), candidates (with name, number, picture and uses: what the user's copies hold of that candidate), links (the to_check links to confirm or reject), statuses, references (collection rows that name the item) and uses.

What the user's rows hold of an item: dict(copies, lines, stock, wishes) (copies that hold it, live part lines, loose stock rows, live wishes).

On a merge row's candidates this says which candidate the user's copies already use (the M.10 note: the migrated part lists name it).

The one item a typed number means for loser (same kind, not itself); a ValidationFailed says when it is none or several.

Merge the local item loser into survivor (one transaction, one event, one receipt). Returns {merge_id, event_id, counts}.

Change an item's kind with its rows (design 3.5). Returns {event_id, from, to, counts}.

Change an item's variant: everything owned moves from from_id to to_id (same kind), and BrickLink's number becomes to_id's (issue #151). One transaction, one event, one receipt. Returns {event_id, from, to, number, counts}.

A to_check link becomes the user's (manual). A Rebrickable candidate of a local item is not confirmed: that is a merge.

Remove a to_check link (Undo puts it back).

Link an item to a typed BrickLink number (manual), for every colour or (color_id, a Brick Work colour) for one. Refused when the item has that number in that scope already, or another item holds it (for one colour: holds it for that colour): that is a merge. (A number scoped to a colour may sit beside another item's unscoped link of it: the lookup tells them apart by the colour, design 3.2.)

Make a link the preferred one of its item and provider: for every colour (color_id None; the link must hold for every colour), or for one colour (design 3.2: a new colour-scoped manual row, or the item's scoped row of that key made preferred). The previous preferred link of that scope loses the mark. item_id, when given, must be the link's item (the item page names its own). One logged change, Undo puts every row back.

The user looked and the item stays unmatched: a to_check status becomes unmatched.

Why an item cannot be merged away, in plain words, or None (design 3.6: a local item, or one the catalogue has retired).

The Links card of an item page: per provider the keys with status, colour scope, preferred and which one answers for colour, plus the provider status rows that have no key. editable is False for an item that is only in the catalogue (nothing to write to yet).

A MergeRefused message in plain words for the merge screen (the refusals of design 3.6).

What merge_in would do, without doing it: runs the merge in a transaction and rolls it back (a write connection is needed).

dict(ok, refusal, rows, dropped, counts): rows = [(table words, rows changed)] biggest first; dropped = rows the survivor already has (kept as they are, the loser's go); refusal = plain-words reason, or None.

Why an item has no Change variant screen, in plain words, or None: a live catalogue figure or part of the collection that is not merged. (The rules of the change itself, such as a set, stay with the preview; a set, an item of yours or a retired one is merged or left alone here.)

The items this one may change to, [dict(item_id, name, number_text, image, kind, year, how)]: live catalogue items of the same kind, never itself.

With no text, the suggestions: items that hold one of this item's BrickLink numbers (any colour scope; how = same_number) and items named by one of its links to check (to_check). With text, the number or name search of the merge page, narrowed to live catalogue items of the kind.

A MergeRefused message of the change of a variant in plain words for its screen (the refusals of issue #151).

What change_item_variant would do, without doing it (a write connection is needed, as for merge_preview).

dict(ok, refusal, busy, rows, photos, number, counts): rows = [(label, n)] for the rows that move, zeros included (loose stock, the lines of figures or parts in copies, wishes); photos = the photos that go with the stock; number = BrickLink's number that follows, or None.

Why a merge cannot be taken back, in plain words, or None: the checks of unmerge_in, read-only.

The merges still standing into an item: [dict(merge_id, merged_id, name, number_text, at, via, blocker, counts)], newest first.

Items the user may merge loser into: those a typed number finds, or (with no text) the candidates the Unresolved list names. [dict(item_id, name, number_text, image, kind, how)], same kind as the loser, never the loser.

The kind of a BrickLink item type letter (S, P, M, G, B, C, I, O).

The BrickLink item type letter of a kind.

What to show for an item (and colour). Raises NotFound for an id neither file knows.

{(item_id, color_id): Label} for many pairs at once (list screens): the same answers as label, in a handful of queries (items, links, colours). A pair whose item neither file knows is left out.

SQL predicate on main.item aliased alias: the item has a number from some provider (a born key) or a confirmed BrickLink link (design 3.8: resolving an unidentified item is adding a link; born keys never change). What the Unresolved list, picture fetch and bulk refresh call "not unidentified".

(BrickLink type, number, colour number) of an item in a colour, or Unidentified when no confirmed link names it.

The colours a part is held or wanted in (copy lines, loose stock and loose figures' parts, wishes), ascending; [None] for a part held in none and for every item that is not a part. What a per-colour source step (pictures, prices) iterates.

The item in the collection: projected from the catalogue (with its links and colours) when it is not there yet.

Writes inside the caller's transaction and does not commit; the caller's commit or rollback decides (store4.identity.project).

The items a typed number may mean, best first: [dict(item_id, kind, name, number, matched_by)].

Order: the born key (the Rebrickable number, or a local item's BrickLink number), then the catalogue's search index over the born and every linked number, then confirmed BrickLink links. kind is a kind (or None for all). A merged item is replaced by the item it was merged into. Search takes both numbers: 3001 and the BrickLink 3001a find the same part when a link says so.

Public input names: key for single-key sources, else the env name without its prefix.

Input names per keyed source, for the Catalogues & keys form.

A keyed source; raises the typed error a client should see otherwise.

Every live stored key's saved_at in one query, for lists.

Key status without decrypting anything: configured, origin (env|stored|null), saved_at.

Resolve key values for a client: complete environment first, then the decrypted store.

A per-user credential slot (rebrickable_user, brickset_user).

Validate write-only input; messages never echo a submitted value.

Encrypt and store a key bundle (replace allowed). Returns the public key state.

receipt, when a list, gets the id of the audit event this call wrote.

Archive the stored key (it stops being used); Undo restores it.

Reverse one save or archive receipt by its event id (core.undo.undo_event).

The credential provider for store4.keys (M.8a): the environment first, then the encrypted source_key table.

path is the collection file, or a callable returning it (looked up at call time, so the app's configuration applies). A source's credentials come from the environment only when all of its variables are set (as credentials does), else from the stored bundle; a missing, archived, undecryptable or unreadable entry is simply "not configured" (None), never an error text.

Make provider(path) the credential source of the 4.0 fetchers. Idempotent; the app calls it once at start.

One budgeted call that proves the key works. The result carries no key material.

Remove every stored key (live, archived, previous) from an in-memory export copy.

secure_delete zeroes the freed pages and VACUUM rewrites the file, so no ciphertext survives in the serialised bytes.

Decorate rows that carry an item_id (identity, colour, picture) using a constant number of queries.

The newest ledger saves, filtered in SQLite: [dict(id, at, receipt=dict(action), receipt_count, undone, undo_available)].

The storage guards, then the generic undo: a created location with contents or sub-locations stays; a moved lot that gained parts in its new storage stays; an item put back into a location that is no longer live stays.

Undo a ledger save by its event id; a second Undo of the same save does nothing.

Undo a ledger save from its history list; a save already undone says so.

Per-storage counts. part_lots is lots plus loose parts that are not inside a lot kept in the same storage.

Figures are minifigures; other is instructions, boxes, gear, books and catalogues. The last row is the virtual "Not stored".

rows are already-loaded storages(db), so a page does not run that query twice.

The Storage page projection: storage_detail plus what the page groups by.

Adds the lot a part sits in (only a lot kept in this same storage) and the lots themselves, and splits the rows into sets, figures, part lots (lots, then loose parts) and other. A lot's size counts only the parts in its own storage, which is what a move carries.

Live references to a storage in three queries, including a lot's own location: [(table, row)], tables copy, stock, lot.

Create or change a storage: type (STORAGE_TYPES or empty), parent_id (another live storage, never itself or one inside it) and note; fields left at KEEP stay as they are. Returns (storage id, event id).

What kind of place a purchase location is; one receipt, Undo in History.

Move copies, loose stock and lots to a storage (None: Not stored). A lot carries its parts that sit in the lot's own storage.

Archive a location and optionally move its live contents to Not stored in one receipt.

Missing items of the chosen copies, combined per item, colour and condition, as the XML export does, except that items with no BrickLink number stay on the list (marked) instead of being left out: a printout is still useful while they wait to be matched.

rows in comparator's order, by keys: each row's values are computed once, not once per comparison.

Stable sorts from the least significant key to the most: the tie-breaks (number, then id, read only where numbers tie), the sort key (reversed where the comparator negates it), rows with a price first for used_price, then the group. Python's sort is stable, also with reverse, so the order is the comparator's.

Record 1 to 500 observations under one receipt; returns their ids.

Undo a manual-price receipt by its event id; a second Undo of the same event does nothing.

The media root for a database file path.

Whether a flag's name says its copy is for sale or to be parted out.

Every live copy with a gap, in set-number order: the ranking row plus parts and figures (the recorded gap), gain (the net gain of repairing it, or None where the ranking gives none), to_sell (the matching flag's name or None) and checking.

Why a copy is left out of the default choice, or None: its sale flag (while sell) or no gain (while gain asks for it).

The rows the search and the theme leave on the screen.

rows in the chosen order (ties by number, then copy).

({(item id, colour id, 'N'|'U'): to buy}, {same key: [(copy id, to buy)]}) over the chosen copies only.

The grouping is planning.export's: the quantity still to buy of each line, per item, colour and condition.

The order list of the chosen copies: dict(lines, skipped, pieces).

A line is gaps.named_lines' (name, colour, condition, BrickLink key) with quantity, the screen's words for the item (number_text, image, colour rgb and ink) and sources: [dict(copy_id, label, quantity)], the largest first. skipped are the lines the file leaves out (no BrickLink number or colour), the same way. pieces is the sum of the lines in the file, a figure counting as many as its quantity.

The line's address in the query: item, colour (0 for none) and condition, <item>.<colour>.<N|U>.

{line key: 'bl'|'pab'} from the query's src values (<line key>.<b|p>); anything else is ignored.

{(item id, colour id): Pick a Brick element id} for the lines: the catalogue's lowest element id of the part in that colour (a part and colour can have several; the lowest is always the same one).

order (from order_list) with every line placed: source ('bl' or 'pab'), element_id (or None), key and price (the BrickLink quote's price as a Decimal, or None), then split: the totals per source.

A line goes where the query's chosen says; else to Pick a Brick when prefer is on and the line has an element id; else to BrickLink. A choice of Pick a Brick for a line with no element id is ignored. Pick a Brick has no price here (its prices are not looked up); the BrickLink total counts the lines with a quote and says how many have none. Shipping is the Repair settings' for the BrickLink part.

The Pick a Brick upload file of the lines placed on Pick a Brick: elementId,quantity, one line each, in the list's order.

The tracker of a request. Built on first use: workbench (the base class) imports add, which registers every undoer through undo, which imports this module, so the class cannot be made while this module loads.

The status of copies as an allocation left it: the copy row and its status flags.

Every line of an order with its document's phase, what was received and what is allocated (live allocations), and its item's kind.

Identity, colour and picture for lines that have an item; the provider's own words for the ones that have not (unplaced).

The newest saves of an order: [dict(id, at, receipt=dict(action), receipt_count, undone, undo_available)].

The allocations of an order, newest first, each with its line, a target label and the event that undoes it (None when it is not the allocation's own save any more).

BrickLink order or inventory XML → (rows, header): the provider's words only, nothing looked up.

A store's order e-mail → (rows, header). A line carries a BrickLink colour name and an item name, no number: the colour name is read through the colour links and the item name stays (name_query) for resolve_names. An instruction line names its set.

Import one document as a draft. Returns dict(order_id, document_id, duplicate, event_id, placed, unplaced): how many lines were placed on an item and how many wait for hand matching. The same document again answers duplicate and writes nothing, unless it was undone: an undone document is not a duplicate, importing the same text again brings it back as a draft with its lines placed anew (#155).

Give a stored order the currency its raw documents name (order_document.raw_record_id -> source_record), when it has none and they agree: orders stored before a currency could stand without a total. One audited, undoable event per order; an order with no document, none that names a currency or two that differ is left as it is. Returns the ids filled. Safe to run again.

Place a draft line by hand: the item the person chose (an id from the catalogue search or a candidate), or a typed number that names exactly one item. A part needs its colour. listed_only (the API's BrickLink key that names no item): only a local item for a number the BrickLink item list names, never a number of another provider.

For each saved line, the copy gaps it could fill: the Workbench's gaps (a loose figure's own parts are not an order's concern), matched by item and colour, a booklet or box by the set's BrickLink number.

The BrickLink wanted-list XML of what is still short: dict(xml, skipped). A line the BrickLink key cannot name (no confirmed number or colour) is left out and listed.

Undo an order save by its event id; a second Undo of the same save does nothing.

Undo from the order's history list; a save already undone says so.

{item id: dict(total, colours, needed_by, needed_count)} for the identified parts and figures item_ids (4.0: items are ids).

Loose stock counts parts and figures held on their own (live, quantity above zero); needed_by lists the live copies whose live, non-spare lines of that item are missing or damaged (a retired line is no line, design 4.4).

'You have 14 in 3 colours: Black 8 (Bin A3), Red 4 (Bin C1)' or 'Not in your collection'.

Order only the groups present; an unused Other section is never inserted.

(choices, unresolved) for recognition predictions of parts and minifigures: core/identify.py maps each number to an item (never guessing between several) and adds what you already hold of it.

An own photo of the piece or set: the file under data/images/own, the row in photo (on the stock row or the copy). Returns the photo id. Add's photo mode keeps its photo the same way.

Add up to 6 identified pieces to loose stock in one receipt. A batch id saved twice returns the first receipt (a retry).

Undo a batch receipt by its event id; a second Undo does nothing.

{copy id: dict(value, currency, lines, priced, enough, unpriced, unpriced_count, unpriced_items)} for live copies.

Lines are the copy's live set lines (a retired line is no line, spares and a figure's own parts excluded) and its live figure lines, each as (item id, colour id): the quantity present is the quantity less the missing. unpriced names up to 50 lines (dict(item_id, color_id)); unpriced_items is the item ids (up to 200) a price refresh could fetch, an unidentified item left out.

Complete, as-is and parted-out side by side for one copy record carrying complete_quote/current_value.

The picture sources to try for an item of kind, in order: the stored setting (kind, else *), else design 6.8's default. A source this module does not know is ignored, so an old value never breaks a job.

A picture of the item for this colour exists: one of that colour, or one with no colour (it serves every colour).

The catalogue's picture URL for (item, colour); a part with no colour takes the "no colour" row. Raises NoPicture.

img.bricklink.com for the item's resolved BrickLink key and colour. Raises NoPicture without a confirmed BrickLink number.

(path, key in the answer) for the Rebrickable API picture of the item, or NoPicture: only a Rebrickable-born item has a number there, and a colour is asked by its Rebrickable colour number (a local, BrickLink-born colour has none).

Could source serve this item and colour right now? (a URL it can name; for the API also a key, since it is a budgeted call)

Is a picture of this item in this colour stored, or could one source of the order fetch it? The Add review warns "no picture known for this colour" when not (design 6.8): no picture_url, no resolvable BrickLink key and no Rebrickable key.

Serve the item's colours that have no picture from source. Returns the number of pictures stored; raises StepDone (unidentified: nothing can picture an item that has no number), StepWait (budget) or StepFailed (some colours remain).

217: the picture of an item being reviewed on Add, fetched now so the review can show it (Ulf, via wiki-agent, 08.11.: "Fetch and

store when selected"). Only items without colours (sets, minifigures and the other kinds; a part's picture depends on the colour chosen later). Returns the picture id, or None when no source has one. A stored picture is a cache, not collection data; the item is projected into the collection (items.ensure) because a picture belongs to an item there; a projected item nobody holds shows in no list. The pictures step's sources in their order, without the Rebrickable API (its daily budget is the jobs'); a source that fails is passed over, so the review never waits.

The pipeline handler (db, job, step) of one picture source; http and image_http are the test seams for the API and the image downloads.

{('pictures', source): handler} for the three sources.

Coverage from database rows only (no file is opened): per kind how many held (item, colour) pairs have a picture, which sources they came from, and how many are unidentified (no source can name them).

The items a refresh would queue: one entry per item (not per colour) of the chosen kinds, missing those with a colour that has no picture, all every held item. Unidentified items are left out (no source can name them) and counted separately.

What the refresh dialog adds up (bw-pictures.js): per kind and scope how many items a refresh would queue, how many unidentified ones it would leave out (unresolved), and unknown_colour, which 4.0 has none of. The dialog also asks for the kind ?.

Queue a pictures job for each of item_ids that is identified, has a colour held without a picture (the missing rule of selection) and has no live pictures job. For the paths that add items without Add's own job (#183): call it after the write commits. One batch per call (#127), so interactive work goes first. Returns the job ids.

Only a step that has not started yet counts as busy: a running one read its colours when it began, so a colour added meanwhile gets a job of its own (Codex review). Queueing is best effort: the write it follows has committed, so a failure here (a locked database, say) is logged and never raised. The caller's receipt stays true, and Refresh pictures finds what is still missing.

217: after copies of a set are written, queue the pictures their parts and minifigures still lack (the set's own picture is its

Add job's step). The parts are the copies' live lines; a copy that later switches to its BrickLink list by itself is queued again by the drainer, and one whose offered list is accepted by hand gets the rest from Refresh pictures. Best effort, like queue_missing: call it after the write (inside a caller's transaction it is part of that transaction).

Queue a pictures job for each selected item that has no live pictures job. Returns (job ids, selected count); with expected_count the call refuses when the estimate on the page no longer matches, so a confirmation is never a surprise.

Run handler(db, job, step) for step when source is the one being tried (M.8f).

Never switch greenlets while this connection holds a transaction.

Cooperate after each unit unless a transaction is still open.

A same-pid row is live only when this process holds its job claim; another pid only when it is the process that claimed: same kernel boot id and same start ticks, NULL identity counting as dead where /proc answers (#167, store4.jobs.pid_alive). Where /proc cannot answer (macOS) the pid alone decides.

A source_priority value: some of the six steps, each {kind or '*': [source ids]}.

The steps to run for an item of kind: import_order:<kind>, else every step in STEPS order.

The source ids a step tries, in order: the local steps use the catalogue; the others the kind's list of source_priority (the setting when it names the step, else DEFAULT_PRIORITY).

Claim up to limit other jobs whose NEXT pending step is step on source (the earlier steps all done or failed), so a handler can ask for them in one call. Not running, not cancelled, no live owner. Each claim is the worker's own (see Pipeline._claim): a job_owner row and state='running' written in one transaction after re-checking the job, so a concurrent worker finds it owned and skips it. A waiting job counts whether or not its retry is due: the caller's own run just proved the budget allows the call. Returns the claims for finish_batchmate / release_batchmate; accept(item_id) lets the caller leave a job out.

The claimed job's step ends done (with a finding code, as a handler's StepDone) and the job goes back to the queue.

Release every claim in claims (best effort: one that cannot be released does not stop the others; it is raised after).

The call failed: the job is exactly as it was before the claim.

A fetch job (store4's kinds: an Add's Rebrickable set or BrickLink part list) may run now: a batch job lets it go first.

139: the pipeline steps that ended waiting for source's key go back in the queue, with their jobs. Inside the caller's open

write transaction (the key's save); returns how many steps.

A batch id for one bulk action (#127): its name and a random tail, such as pictures-3f9a1c2b.

The newest bulk actions, newest first: each batch's steps, its counts by outcome and its failures (item, reason) for the Jobs row.

Stop what is left of a batch: its jobs not started yet, or waiting for budget, end as failed with Cancelled and no retry. A job running right now finishes. Returns how many were cancelled. One event for the batch.

Run the pipeline jobs that may run now; the results of the jobs this call ran.

Queue the normal import for items that are new to this store and have no job yet (Add's rule, for imports and sync).

Linear-interpolated 90th percentile, rounded up to a whole multiple.

One ordering rule for planning, its public list and value cursors.

Pure projection. Inputs are copy records, complete quote and missing lines.

Lines already carry the shared Workbench gap and stock projection. Decimal values retain precision; no currency conversion.

The repair and price settings from setting, with the documented defaults for what is not stored.

Lean Prices projection (M.8f): one row per priced (item, colour), no observation lists.

Four bounded reads, none of them per row. The row's stale flag is true when any current quote is past its source's freshness; the display price is chosen from each (condition, source, guide)'s freshest successful observation with Collection's own selection rules. The full observation list of one identity is price_details, loaded on demand. kind is a screen letter (S, P, M, ...): only that kind's items. Voided observations never show.

Compact positional Prices rows (see PRICE_FIELDS): identity, kind, owned/wanted, the display price as text with its age and stale flag, and the item id the page links and refreshes by. Refresh is available to every row that is not unresolved.

One identity's observation list for the Prices Details disclosure, display text only.

One bulk observation read for the identities of rows (items with item_id, color_id); Collection's condition/source selection.

Every row gets price_records (its observations, newest first, a voided one never), condition_prices and display_price: the price at the wish's condition when it names one, else the best overall.

The max a quote is held against, with its currency: a boxed quote (slot 'boxed') against the wish's max with box when it has one (#131), else, like every other quote, against its max.

Compare a quote on a wish (by default the price shown, display_price) with the max it is held against (max_limit).

State is 'under' (price at or below the max), 'over', 'differs' (both currencies known and different and no rate for them) or None (no max, no price or a max without a recorded currency). margin = max minus price, only for a real comparison; a converted price is kept on the row under conversion.

A wish's two verdicts: the price shown against its max (max_state, max_margin) and, for a set with a quote with box, that quote against the max with box, or the max when no max with box is set (max_boxed_state, max_boxed_margin, #131).

The live wishes of every active list, as Collection lists them, with the price shown, the comparison with the max, how much is filled and the retail line of a set. Filled lines drop to the bottom (#35); the order within each part stays as listed.

Complete sets: every live copy with a gap, grouped and ranked (compute), decorated for the screen: rows is the whole list in screen order (ranked, free repairs, outside break-even, needs evidence) and settings the configuration used.

pin (id, pinned: a boolean) sets copy.pinned; settings (values: all five repair settings) writes them to setting. One audited event each; returns its id.

Undo a pin or a settings save by its event id; a second Undo of the same event does nothing.

The BrickLink Wanted List of the chosen copies' repair lines: dict(xml, lines, skipped) as gaps.export, but the quantity of a line is what is still to buy (the gap less the loose stock the repair settings let it use). A copy with no gap is not on the list.

The stored result of an applied plan ({event_id, counts, at}), or None.

Record the plan as applied (result: event_id, counts, at); a second mark for the same plan fails.

The saved found counts as {"item:colour": n} (empty when none, or unreadable).

Every piece the lot holds, whatever its condition (parts and whole figures).

The pull list as data: dict(lot, set, lines, totals, lot_pieces, nested, refusal).

lines are dict(key, item_id, color_id, kind, need, held, ticked, found, category_id, category) (a whole figure has kind figure and no colour; the caller orders them, the names live in the item tables). totals count pieces: need, held, found, to_find, lines, lines_to_find, figures_need, figures_found. refusal is the sentence Make it a copy would be refused with, or None. Raises errors.NotFound (no such lot or set) and ValueError (no catalogue, or a set with no part list).

The three numbers of the confirm: dict(moves, missing, stays) of a state: found pieces leaving the lot, the rest recorded as missing, what stays.

Save the found count of one line (an absolute count, held included): 0 to need; a count below held leaves the pieces the lot already has as they are. Idempotent, writes no event. Returns the line as state shows it. ValueError: the line is not on the list or the count is out of range.

[(stock id, amount)] so that every line of the list gets min(have, need) from the lot's rows, the largest usable row first, then the lowest id (the order of build_scout.plan_takes, which reads the parts index and so cannot plan a set of whole figures only).

Make it a copy: the found pieces of the pull list move out of the lot into a new copy of the set, one transaction, one undoable event. Returns dict(event_id, copy_id, pieces, figures, missing_parts, missing_figures, completeness, stays). Refused (ValueError, nothing written): a set made of other sets, nothing found yet, no part list; errors.NotFound for a lot or set that is not there.

{item id: dict(price, currency, country, first, last, status)} for the sets that have any of it.

'20 % under retail' style comparison, or None when it cannot be compared honestly.

39: another currency is compared when both rates exist; the result then says converted.

Statistics (5c): price paid against retail per currency, per purchase year and per theme.

The currency totals are shown in: display_currency, else the BrickLink currency, else EUR.

Return secret values of at least eight characters, longest first.

Ignore variable prefixes. Default to the live environment; callers may also supply app configuration.

secret.key beside the collection (the data folder that holds brickwork.db).

Encrypt a source credential or JSON bundle; the caller stores only ciphertext.

Fail closed with fixed text when the secret changed or ciphertext is invalid.

True when a secret key (BW_SECRET_KEY or secret.key) can encrypt; never reveals why a bad value is bad.

Keyed digest of a JSON-able secret payload, for idempotent replay without storing a plain hash.

What names the attached catalogue build: its id space, its newest build, the file's stamp and the collection's activations. A rebuild, a new download or a swapped file changes it.

The catalogue's set and figure inventories (latest, live, spares left out) as Rows. db has the file attached as catalogue.

Index from Rows. Memory is two small arrays per line, not a tuple per posting.

The index of the attached catalogue, built once per catalogue build and process (a new build replaces it).

{line key: quantity} from {(item id, colour id or None): quantity}; a quantity below 1 is no line.

(ranked rows, matched line count): one (position, evidence, covered quantity, covered lines, complete lines, distinctive found) per set that shares a line with the input, best first.

{line key: {flag name, ...}} for the flags that sit on a line of the (cleaned) input (a sticker confirmation, sticker:<id>, is not a flag a person sees: stickers_of reads it).

{line key: frozenset of the set item ids the sticker is confirmed for} for the lines flagged Sticker (the empty set: not chosen yet).

What a sticker-flagged line adds to a set's evidence on top of its own share there (can be negative: a confirmed sticker replaces the share).

The ranked rows with the sticker evidence added and sorted again (the cached ranking itself is never changed).

(index, (ranked rows, matched line count), index built now, ranking from the cache) for cleaned input lines: the whole ranking, not a page, so a caller that filters the sets itself (candidate sets, #200) can page after it. Cached per catalogue build and input.

The ranked sets for a parts multiset, dict(catalogue, input, total, limit, offset, cached, results).

parts is {(item id, colour id or None): quantity}; flags optionally {(item id, colour id or None): {flag name, ...}}, passed through to each set's matched lines and summed per flag. Results are cached per input and catalogue build (the ranking; the page's detail is rebuilt, it is cheap). Read-only.

(parts, flags) of the live loose stock in a lot (its flags are the stock rows' tags). ValueError when there is no such lot.

(parts, flags) of the live loose stock kept in a storage, and in the storages inside it unless below is false.

(parts, flags) of all live loose parts and figures.

(parts, flags) of a saved selection of stock rows (ids of live rows; a missing or archived one is ValueError).

(full key or None, partial dimension or None, the remaining words).

Make the pipeline run the source steps: pictures (three sources), Brickset metadata, BrickLink prices. options are the test seams (http for the API calls, image_http for downloads, root for the picture cache). Idempotent.

What the Catalogues & keys list shows of a source: its switch, key state and the day's budget.

The id of the live tag flag named Sticker (any case), or None.

(flag id, created): the Sticker flag, made as a visible tag when the collection has none yet.

The live loose part stock_id in lot lot_id as a dict (name, number, colour); errors.NotFound when the lot has no such part line.

The confirmed sticker of a stock line as dict(set_item_id, sheet_item_id, set_number, set_name, event_id), or None.

{stock id: dict(flagged, confirmed)} for the stock lines: flagged is whether the Sticker flag is on it, confirmed its decision (only while flagged).

The sets a sticker on this part line may belong to: dict(stock, total, limit, offset, results).

Each result is a live catalogue set (not retired) whose latest, live inventory holds the part in the line's colour (spare lines left out, ADR 0011) and at least one sticker sheet (a part of the category Stickers, by name): set_item_id, set_number, set_name, year, sheet_item_id, sheet_number, sheet_name and sheet_picture (the catalogue's picture address, or None). A set with several sheets is one row, its sheet with the lowest number first. Sets with a sheet picture come first, then the earlier year, then the number.

Record "This one": the sticker on this part line is the sheet sheet_item_id of set set_item_id, one event (undoable). The pair must be one of the line's candidates; the line must hold the Sticker flag. Choosing what is already chosen writes nothing. Returns dict(event_id, changed).

Record "Not a sticker": the Sticker flag leaves the line and a confirmation, if there is one, stops counting; one event (undoable). A line without the flag writes nothing. Returns dict(event_id, changed).

The part lines of a loose figure as text (every column that a check, a Take or Give or a mark can change), for an Undo to compare.

Something made after the row was added that points at it or at its part lines: a Take or Give (into it, or out of it), an allocation.

Add quantity of an item to loose stock: onto the live row with the same merge key, else a new row. A part needs a colour and any other kind has none. Returns the change {id, created, quantity, before, after} (rows as dicts), which is what undo_added needs and what the Add receipt keeps. record=False writes no audit event: the caller's own event is the receipt (the pull list's Make it a copy).

Reverse one add_loose change: archive the row it created, or take its quantity (and the state it merged in) back off the row it increased. Refused when the row differs from what the add left (any later change: edit, merge, take, a later add onto it), when a loose figure's part lines differ from what the add left, or when a Take / Give or an allocation points at the row or its lines.

Where an edit of live stock rows lands: [(row id, target id or None)], in the order the rows are given.

A row whose merge key, once edits are applied, equals the key of another live row merges into it (invariant 9: one live row per key). The other row is a stock row outside the selection, or a selected row that kept or took that key earlier in the order. A loose minifigure never merges (it carries its own part list); a selected row whose key does not change targets itself. One query finds the outside rows however many rows are edited.

The state of a pile a second pile was added onto: counts added (None only when neither has one), capped by the new quantity; checked stays only when both were checked (the rule of a stock merge on edit).

Write an edit as plan_edit planned it, inside the caller's transaction, in a fixed number of statements however many rows.

A row that merges is archived with the edits applied (so its merge key names the row it went into) and its quantity, missing and damaged counts are added to the target (checked stays only when both were checked); every other row takes the edits. Each row a merge touches also gets its own merge event with the row before and after.

Exchange username + password at the site for its token/hash and store only that, encrypted.

The password is used for one request and dropped; it never reaches the database, an event, a log line, an error or a reply.

Store a token/hash the user generated on the site (write-only).

Which remote lists are used. Rebrickable: owned (list ids, empty = all but the wishlist list), wishlist (one list id or null), send_to (the owned list that receives sends). Both sources: wish_list (the Brick Work wishlist that pulls and sends wishes, default 'default').

Remote set number -> the item id it names, or None. A number is a Rebrickable number (Brickset's number-variant is the same numbering): the item whose born key it is (a local BrickLink-born item counts by its BrickLink number), else the one item a confirmed BrickLink link names; a number that names several items, or none, or only a part or figure, is None (the plan lists it as not matched).

Item id -> the set number a site knows it by: the Rebrickable number of a Rebrickable-born item, else the BrickLink number (items.bricklink_key; a local BrickLink-born item is its own). An item with no number at all is None: it is left out and listed.

What the site has that Brick Work lacks. Writes nothing to the collection.

Place one copy per missing unit of a set (design 4.3's preselection; flagged, condition and completeness unset), loose stock of the other kinds, and the missing wishes, in one transaction with one receipt. Never deletes or lowers anything here.

Reverse one pull exactly (core.undo); refused when anything it wrote was changed since.

The remote calls a send would make: one row per set whose count differs. Removals unticked.