portage-ucp-journal¶
The buyer-side purchase journal, plus the injectable Store abstraction it's built on —
backs portage history in the CLI.
Portage::Ucp::Journal¶
A buyer-side, append-only purchase journal for portage-ucp — store origin,
source, product, amount (minor units + currency), order id, idempotency key,
and timestamp for every completed purchase — built on a small, injectable
Store interface in the same mold as core's RateLimiter/Authenticator
(design-log §22).
This gem has no runtime dependency on portage-ucp itself, and portage-ucp
has none on this gem — core's Dispatcher gained an optional journal:
argument (nil by default, a no-op when absent) rather than requiring this
gem. You opt in from your own app.
Usage¶
require "portage/ucp/journal"
journal = Portage::Ucp::Journal::PurchaseJournal.new # FileStore, ~/.portage/journal.jsonl, by default
dispatcher = Portage::Ucp::Dispatcher.new(adapter: my_adapter, journal: journal)
# ... complete_checkout dispatches as normal; each settled checkout that
# produces an order confirmation now gets one journal entry per line item.
journal.all
# => [{"shop"=>"example.myshopify.com", "source"=>"adapter:shopify",
# "product_id"=>"sku_1", "quantity"=>2, "amount"=>2000, "currency"=>"USD",
# "order_id"=>"order_1", "idempotency_key"=>"idem_1",
# "recorded_at"=>"2026-09-15T12:00:00Z"}, ...]
Swapping the store¶
PurchaseJournal.new(store: your_store) accepts anything implementing
Portage::Ucp::Journal::Store's two methods (#append(record),
#each_record(&block)). FileStore is the shipped default; nothing else
ships today (see docs/plans/storage-abstraction-journal.md's open
decisions) — write your own Store subclass for Redis, a real database,
or an in-memory double for tests.
What this is not¶
- Not
Support::TransactionLog(payment-dispatch bookkeeping — reserve/ commit, spend caps) orSupport::OrderLedger(a settled-order snapshot keyed for lookup). Both stay in coreportage-ucp— as of design-log §33 they gained the same pluggable-Storeseam this gem has, but the classes themselves did not move. - Not a console, a CLI history command, or a scheduler. This gem is the
write path and the shared
Storeseam those would read from and build on, not the read/UI surface itself.