portage-ucp-journal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9eff21bdd3bd61e9e0d06d28fb1730bdb6341cf03b3655ba314c374a6f300a22
+  data.tar.gz: db616a0e139f3cf13ada29d12995f3d7905993ba33da43b79b29b560d174105b
+SHA512:
+  metadata.gz: b78d052fe12a74a7bd05f75a83604c0c50c4670188bfc2ad75fc94c7d3dde6916b34485eaf97e66c487d3ac03046cabe92e90f2a29757584a0237b18410789eb
+  data.tar.gz: 1abe91206ecf4972ab684c0579e80b8e3ae49ba726e5d9ab3986fa4e7660e0b2c845c287d67e19767125694e5f04596c9417130eb9d3dbfcb55c70107cc0176b

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/);
+this project is pre-1.0, so APIs may still shift between minor versions.
+
+## [0.1.0] - 2026-09-15
+
+- Initial release: `Portage::Ucp::Journal::Store` (the injectable, append-only
+  persistence seam design-log §22 asks for), `FileStore` (its JSON-Lines
+  default), and `PurchaseJournal` (one entry per line item of a settled
+  `Order` — store origin, source, product id, quantity, amount in minor
+  units + currency, order id, idempotency key, timestamp).
+- No runtime dependency on `portage-ucp` — wires into `Dispatcher` via its
+  new optional `journal:` argument from the consumer's own app.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Whitbread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,50 @@
+# 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
+
+```ruby
+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) or `Support::OrderLedger` (a settled-order snapshot
+  keyed for lookup). Both stay in core `portage-ucp` — as of design-log §33
+  they gained the same pluggable-`Store` seam 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 `Store` seam those would read from and build
+  on, not the read/UI surface itself.

data/lib/portage/ucp/journal/file_store.rb

@@ -0,0 +1,61 @@
+require "json"
+require "fileutils"
+
+module Portage
+  module Ucp
+    module Journal
+      # Default Store: a JSON-Lines file, one record per line. Genuinely
+      # append-only — unlike core's TransactionLog/OrderLedger, #append never
+      # reads or rewrites the whole file, so a large journal stays cheap to
+      # write to and a crash mid-append can only ever lose the one
+      # in-flight line, never corrupt an earlier one.
+      #
+      # Same raising-write posture as TransactionLog/OrderLedger: a lost
+      # write here is a silent hole in the buyer's own purchase record, so
+      # there is no `rescue StandardError; nil` anywhere in this class.
+      class FileStore < Store
+        PATH = File.join(Dir.home, ".portage", "journal.jsonl").freeze
+
+        def initialize(path: PATH)
+          super()
+          @path = path
+        end
+
+        def append(record)
+          FileUtils.mkdir_p(File.dirname(@path))
+          File.open(@path, File::WRONLY | File::CREAT | File::APPEND, 0o600) do |file|
+            file.flock(File::LOCK_EX)
+            file.write("#{JSON.generate(record)}\n")
+            file.flush
+          end
+          record
+        end
+
+        # Skips a torn trailing line (a crash mid-write leaves at most one
+        # unparseable final line) rather than raising — every earlier,
+        # complete line is still good and must not be lost because the last
+        # one wasn't. A torn line in the *middle* of the file would indicate
+        # something worse than a crash mid-append (the file was hand-edited,
+        # or two writers bypassed the flock) and is left to surface as a
+        # JSON::ParserError rather than silently swallowed anywhere but the
+        # last line.
+        def each_record
+          return enum_for(:each_record) unless block_given?
+
+          return unless File.exist?(@path)
+
+          lines = File.open(@path, File::RDONLY) do |file|
+            file.flock(File::LOCK_SH)
+            file.readlines
+          end
+
+          lines.each_with_index do |line, index|
+            yield JSON.parse(line)
+          rescue JSON::ParserError
+            raise unless index == lines.length - 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/journal/purchase_journal.rb

@@ -0,0 +1,86 @@
+require "time"
+
+module Portage
+  module Ucp
+    module Journal
+      # Buyer-side, append-only record of "what did I buy, where, for how
+      # much" (design-log §22) — distinct from core's TransactionLog
+      # (payment-dispatch bookkeeping) and OrderLedger (a settled-order
+      # snapshot keyed for later lookup). Neither of those is shaped as a
+      # journal, and neither belongs to a consumer wanting one durable
+      # append-only trail across every completed purchase regardless of
+      # which adapter or platform made it.
+      #
+      # Takes only what's already in hand at the dispatcher's settle point —
+      # no re-fetch, no new schema. `checkout` is duck-typed against
+      # Portage::Ucp::Checkout (currency, line_items — each a LineItem-shaped
+      # object with #item.id, a bare integer #quantity, and #totals, an
+      # array of Total-shaped objects with #type/#amount — and #order, an
+      # OrderConfirmation-shaped object with #id), not against
+      # Portage::Ucp::Order: Checkout#order is only ever an
+      # order_confirmation stub (id/permalink_url/label per the UCP schema),
+      # never the full Order with its own line_items. This gem carries no
+      # runtime dependency on portage-ucp itself either way.
+      class PurchaseJournal
+        def initialize(store: FileStore.new, clock: -> { Time.now })
+          @store = store
+          @clock = clock
+        end
+
+        # One journal entry per line item — a checkout with several distinct
+        # products is several purchases from the buyer's own point of view,
+        # not one.
+        #
+        # @param shop [String, nil] merchant/store identity, same value
+        #   Dispatcher already threads into TransactionLog.
+        # @param source ["native_ucp", String] "native_ucp" for a
+        #   direct/no-adapter dispatch, "adapter:<platform>" otherwise — see
+        #   docs/plans/storage-abstraction-journal.md's open decision on the
+        #   exact platform string.
+        # @param checkout [#currency, #line_items, #order] the settled
+        #   Checkout — Dispatcher's `result` at the complete_checkout settle
+        #   point, same object #order_ledger snapshots `#order` from.
+        # @param idempotency_key [String] joins this entry back to the
+        #   TransactionLog/OrderLedger records from the same dispatch.
+        # @return [Array<Hash>] the entries written, one per line item.
+        def record_checkout(shop:, source:, checkout:, idempotency_key:)
+          context = { shop: shop, source: source, order_id: checkout.order&.id,
+                      idempotency_key: idempotency_key, recorded_at: @clock.call.utc.iso8601 }
+
+          checkout.line_items.map do |line_item|
+            entry = build_entry(line_item, checkout.currency, context)
+            @store.append(entry)
+            entry
+          end
+        end
+
+        def each_record(&)
+          @store.each_record(&)
+        end
+
+        def all
+          enum_for(:each_record).to_a
+        end
+
+        private
+
+        def build_entry(line_item, currency, context)
+          {
+            "shop" => context[:shop], "source" => context[:source], "product_id" => line_item.item.id,
+            "quantity" => line_item.quantity, "amount" => line_total(line_item), "currency" => currency,
+            "order_id" => context[:order_id], "idempotency_key" => context[:idempotency_key],
+            "recorded_at" => context[:recorded_at]
+          }
+        end
+
+        # Total#amount is a bare integer minor-unit amount — same convention
+        # Dispatcher#settled_amount already follows for the checkout-level
+        # total.
+        def line_total(line_item)
+          total = Array(line_item.totals).find { |t| t.type == "total" }
+          total&.amount
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/journal/store.rb

@@ -0,0 +1,30 @@
+module Portage
+  module Ucp
+    module Journal
+      # @abstract Pluggable append-only record store — same "no bundled
+      #   storage assumption" posture as core's RateLimiter/Authenticator
+      #   (portage-ucp §9), extended here to persistence (design-log §22).
+      #   Unlike NullRateLimiter/UnconfiguredAuthenticator, there is no
+      #   silent-no-op default: an unconfigured journal that drops every
+      #   write defeats the point of a purchase record, so FileStore (this
+      #   gem's own default) is a real, durable implementation, not a null
+      #   object. The interface is deliberately minimal — append and replay
+      #   only — because the only consumer today (PurchaseJournal) needs
+      #   nothing more; extend it when a second real consumer (a console, a
+      #   scheduler) needs keyed lookups, not speculatively ahead of one.
+      class Store
+        # @param record [Hash] a single journal entry, already built by the
+        #   caller (PurchaseJournal). The store persists it as-is.
+        def append(record)
+          raise NotImplementedError, "#{self.class} must implement #append"
+        end
+
+        # Yields each previously-appended record, in write order, without a
+        # block returns an Enumerator.
+        def each_record(&)
+          raise NotImplementedError, "#{self.class} must implement #each_record"
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/journal/version.rb

@@ -0,0 +1,7 @@
+module Portage
+  module Ucp
+    module Journal
+      VERSION = "0.1.0".freeze
+    end
+  end
+end

data/lib/portage/ucp/journal.rb

@@ -0,0 +1,16 @@
+require_relative "journal/version"
+require_relative "journal/store"
+require_relative "journal/file_store"
+require_relative "journal/purchase_journal"
+
+module Portage
+  module Ucp
+    # Buyer-side purchase journal + the injectable Store abstraction it's
+    # built on (design-log §22) — kept out of the dependency-light core gem
+    # (portage-ucp §2) since it's an optional consumer add-on, not a
+    # payment-safety-critical concern the way TransactionLog/OrderLedger
+    # are. A future console or scheduler gem depends on Store the same way.
+    module Journal
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: portage-ucp-journal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tom Whitbread
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: portage-ucp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 'An append-only, consumer-swappable record of every purchase a Dispatcher
+  completes (store origin, source, product, amount in minor units, order id, idempotency
+  key), built on a small Store interface in the rate_limiter/authenticator mold —
+  the shared persistence seam design-log §22 asks for so a future console or scheduler
+  gem doesn''t each grow an incompatible one. Zero runtime dependency on portage-ucp
+  itself; wires in via Dispatcher''s optional journal: argument.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/portage/ucp/journal.rb
+- lib/portage/ucp/journal/file_store.rb
+- lib/portage/ucp/journal/purchase_journal.rb
+- lib/portage/ucp/journal/store.rb
+- lib/portage/ucp/journal/version.rb
+homepage: https://github.com/tomtom87/Portage/tree/main/portage-ucp-journal
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-journal
+  changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-journal/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Buyer-side purchase journal + injectable Store abstraction for portage-ucp
+test_files: []