The bridge

This is the one recipe in invoice-book that reads another pack, and the pack declares that dependency rather than reaching across quietly.

⛔⛔ AN HOUR CANNOT BECOME TWO BILLABLE ITEMS. Every item this creates carries the time entry's id in source_ref, and a second pull skips anything already carried across. It looks each candidate up by that id (source_ref in the candidates' ids), never by reading a page of every item ever pulled: until 2026-10-11 it read 200 items in id order, which is no order at all, so once more than 200 existed the check could miss the one item that mattered. Without that, pulling the same range twice would put the same hour on two invoices — the exact failure bill-period's never-bill-twice guard exists to stop, arriving through a side door that guard cannot see.

⛔⛔ PULLED HOURS ARE MARKED CLAIMED IN billable-hours, with invoice_ref set to item:<id> so the claim points at what made it. This is deliberate and it is the opposite of what an earlier version did.

⚠ Two packs write that flag, and that is correct — because they write it with the SAME meaning: this hour has been claimed for billing. bill-period claims by invoicing directly; this claims by turning the hour into a pending item. A single guard then covers both paths. The version that left the entries untouched had the opposite property: neither path could see the other, so an hour pulled here could still be billed there, and keeping the two ledgers straight was left to whoever remembered.

⚠ A claim is not an invoice. Delete the pending item and the hour stays claimed — the same as running bill-period and never sending the invoice. invoice_ref carries the item id so you can see what happened.

⚠ If a claim fails the card says so loudly. An hour that became an item but was not claimed is exactly the double-billable state, and it must not be reported as a clean run. Running it again finishes the job: an unclaimed hour that already has an item is claimed against that item, and no second item is made. (Until 2026-10-11 the re-run skipped it, claimed nothing and said nothing, so the hour stayed billable.)

⚠ One run pulls at most limit entries (200), oldest first from the start of the range. The range is read upward from its start, so older unbilled hours cannot fill the page and hide it (they did until 2026-10-11: 200 unbilled hours before the range pulled nothing in it). When a run reaches the limit the card says there may be more; run it again.

⚠ Pricing happens here, once, at the rate you give. Items carry money; hours carry minutes. Changing the rate afterwards does not reprice an item that already exists, which is correct — you decided a price.