omp-worklog 0.14.6 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ee816df2ce095811beb7021f32892defbbf488840f02f0ff6e3019897f5298c
-  data.tar.gz: 443a96a73fa7bd0f4d4c37089712e1fe7126f5bc6d2800be843bf727b816667b
+  metadata.gz: c9b72c4c74b6a576facff2242076d619179a1e2b441aef3617f98d4357018839
+  data.tar.gz: 5d0f548e70de14535544d1f0ab66d6c3060a4cacf4393fe11dfead4b5941b68c
 SHA512:
-  metadata.gz: 2f54d4a599a17e35d500617c0aa7f44fa591f9167861343a414b3d650266b0c0e843dcdc4f84009f81c9939260b26bef867e00d43fd743418518895c7d7fd83c
-  data.tar.gz: 4a89084e3d29bc60fac8eaf06da3c409ec0b165fefc316f5d65777864f61cb2c0fbe55f33829589679d5a7608b74c087a27f89c56db39c725c0782569d4d1bc2
+  metadata.gz: 6c9e6f039e18d6a5ef5e93519d4241a7f285fa82c9958cad5d5f2d966b1775f0aa347e14cee382802d3023a59ed424b15d1634c05863800194f022d94cb21fca
+  data.tar.gz: e351d67770dc43500ab63ca325427fdd4aa22559c7690bea961abc6cc6dab194e342c601c72fc672b6ad5c7b5a04d4fbbf545e784f804ff497168ce28fa5c76f

data/README.md

@@ -1,6 +1,6 @@
 # OMP Worklog
 
-OMP Worklog is a Project Time-driven Ruby CLI and OMP plugin that builds reviewable personal work logs from local evidence. Harvest is currently one manual destination: the only Harvest operations are explicitly requested time-off and ordinary-work writes.
+OMP Worklog is a Project Time-driven Ruby CLI and OMP plugin for reviewed personal work logs. It reports human/AI observations separately, prepares independent concurrent-project candidates, and files a reviewed daily batch to Harvest after explicit approval. Time-off and ordinary-work commands remain available.
 
 ## Documentation
 
@@ -77,7 +77,21 @@ User stories:
 
 The observable contract is a deterministic block of at most 22 physical lines followed by a generated section of at most six lines, keeping the complete result within 30 logical lines. Every total stacks date, exact local project, aggregate duration, and configured Harvest project/task or `Review destination` on separate lines. The generated section uses the `AI-generated work summary (review before use)` heading, one to three concise outcome bullets derived from at most eight duration-ranked evidence records, and a clearly review-marked suggested Harvest note. Generated lines are capped at 100 characters with an ellipsis so one verbose model line cannot consume the screen. In interactive mode, one keyed OMP widget is updated from the generation state to final content; print and RPC modes retain a normal transcript message. The command remains review-only and never writes Harvest.
 
-Type `/worklog ` in OMP to discover `timesheet`; date aliases appear after selecting `timesheet `. After `--project`, Tab lists local human-active Project Time project names. Completion preserves the exact local project name.
+Type `/worklog ` to discover timesheet, stats, plan, and submit. Date aliases are completed contextually. After `--project`, timesheet completion lists human-active projects; stats and plan also include agent-only projects. Completion preserves exact local project names.
+
+### Daily Human and AI Reports and Reviewed Batches
+
+```text
+/worklog stats 2026-10-05 2026-10-18
+/worklog stats today --until 12:00
+/worklog plan yesterday
+/worklog submit "PATH-PRINTED-BY-PLAN" --dry-run
+/worklog submit "PATH-PRINTED-BY-PLAN"
+```
+
+Different projects retain independent candidate durations; overlapping human/agent evidence within one project is counted once. Only same-session gaps within the five-minute response grace may be inferred, and historical progress/blocker state still needs review. Plans are private, unapproved JSON files with required factual notes and reviewer-adjusted durations. The interactive submit asks for one explicit approval, preflights every record, and then files the batch with duplicate and uncertain-outcome protection.
+
+See [reviewed concurrent worklogs](/docs/billing.md) for the policy, review fields, CLI/tool interfaces, private backups, and recovery. Headless callers can use `omp-worklog work-entry-batch [--dry-run]` with a reviewed JSON document on stdin; actual writes require `approved: true`.
 
 ## OMP settings
 
@@ -88,6 +102,7 @@ Worklog resolves persisted user settings and project overrides through the suppo
 - `command`: direct path to the `omp-worklog` executable.
 - `projectTimeLogPath`: optional path to Project Time v1 evidence; defaults to `~/.omp/project-time/time-log.sqlite`. A legacy versioned JSON snapshot is also supported.
 - `projectTimeMappings`: optional JSON mapping of exact local projects to Harvest project/task names; defaults to `{}`.
+- `responseGraceMinutes`: same-session response-gap inference for review candidates; defaults to `5`, with `0` disabling gap inference. This does not certify progress or authorize billing.
 
 The host stores user plugin settings in `~/.omp/plugins/omp-plugins.lock.json` and project overrides in `.omp/plugin-overrides.json`. Back up private configuration outside Git before uninstalling/reinstalling a plugin. Worklog deliberately does not parse these files itself or bypass project precedence.
 
@@ -113,14 +128,18 @@ For independent comparison with manually recorded Harvest entries, follow the [p
 
 `omp_worklog_preview_project_time_transforms` emits deterministic JSON for local raw intervals. It accepts an inclusive date range and optional exact `repositoryId`, `project`, and `sourceKind` filters; each matching interval is split by local date and grouped by activity, with missing labels reported as `unlabelled`. It defaults to `human_active` and returns the effective top-level `sourceKind`; selecting `agent_turn_elapsed` requires an explicit source-kind request. Set `applyMappings` to create configured Harvest destinations or review-required local destinations for every included group. The output reports groups and draft entries; it never writes Harvest.
 
-
-
 ## Migration from Harvest Worklog
 
 Version `0.14.0` is a clean identity cutover. Uninstall the retired `harvest-worklog` gem and OMP plugin, then install `omp-worklog`; replace former `harvest-worklog` CLI and `/harvest-worklog` command invocations with `omp-worklog` and `/omp-worklog`. The retired package, executable, command, tools, module, and settings aliases are not retained.
 
 Version `0.14.3` renames the OMP slash command from `/omp-worklog` to `/worklog`; the `omp-worklog` package identity and CLI executable are unchanged.
 
+## Changes in 0.15.0
+
+- Add daily/project human-active and AI elapsed reports with a final-day cutoff.
+- Prepare private concurrent-project review batches with within-project deduplication and five-minute same-session response grace.
+- File explicitly approved batches with user-scoped preflight, stable identities, private receipts, and safe partial/uncertain-result handling.
+
 ## Changes in 0.14.6
 
 - Activate persisted settings through the supported host CLI before registering commands, completion, and tools.
@@ -143,7 +162,7 @@ Version `0.14.3` renames the OMP slash command from `/omp-worklog` to `/worklog`
 Before merging a release PR, self-review its complete diff, address every actionable review comment, and rerun focused QA after fixups. Record the review and QA evidence on the PR. Then merge to `main`, build and publish the Ruby gem, install the released OMP plugin from GitHub, and verify it:
 
 ```bash
-ruby test_omp_worklog.rb
+npm run test:ruby
 npm run test:omp
 bin/omp-worklog --help
 VERSION="$(ruby -Ilib -romp_worklog/version -e 'puts OmpWorklog::VERSION')"

data/lib/omp_worklog/batch_cli.rb

@@ -0,0 +1,755 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "optparse"
+require "tempfile"
+
+module OmpWorklog
+  class BatchCLI
+    FORMAT = "omp-worklog/review-batch"
+    RESULT_FORMAT = "omp-worklog/batch-result"
+    ID_PREFIX = "omp-worklog-v1:"
+    RECEIPT_FORMAT = "omp-worklog/submission-receipts"
+    PER_PAGE = 200
+
+    TOP_LEVEL_KEYS = %w[format version approved from to policy entries].freeze
+    POLICY_KEYS = %w[mode responseGraceMinutes].freeze
+    ENTRY_KEYS = %w[
+      id spentDate localProject project task candidateMilliseconds milliseconds
+      humanActiveMilliseconds agentTurnMilliseconds bridgedGapMilliseconds
+      sourceEntryIds notes reviewed reviewReasons
+    ].freeze
+
+    class InputError < StandardError
+      attr_reader :code
+
+      def initialize(code)
+        @code = code
+        super(code)
+      end
+    end
+
+    class ProviderFailure < StandardError
+      attr_reader :code
+
+      def initialize(code)
+        @code = code
+        super(code)
+      end
+    end
+
+    def self.run(arguments, input: $stdin, output: $stdout, error: $stderr, client: nil, environment: ENV)
+      new(arguments, input:, output:, error:, client:, environment:).run
+    end
+
+    def initialize(arguments, input:, output:, error:, client:, environment:)
+      @arguments = arguments.dup
+      @input = input
+      @output = output
+      @error = error
+      @client = client
+      @environment = environment
+      @dry_run = false
+      @state_dir = nil
+    end
+
+    def run
+      parse_options!
+      batch = parse_and_validate_batch!
+      require_approval!(batch)
+      @account_id = account_id_from_environment
+      client = @client || Marlens::HarvestApiV2::Client.from_environment(environment: @environment)
+      user_id = current_user_id(client)
+
+      store = ReceiptStore.new(receipt_directory, @account_id, user_id)
+      result = if @dry_run
+                 preflight_result(batch, client, user_id, [store, store.read_only])
+               else
+                 store.with_lock do |receipts|
+                   preflight_result(batch, client, user_id, [store, receipts])
+                 end
+               end
+
+      emit_result(result)
+      successful_result?(result) ? 0 : 1
+    rescue InputError => error
+      emit_failure(@dry_run ? "preflight" : "submit", error.code)
+      1
+    rescue ProviderFailure => error
+      emit_failure(@dry_run ? "preflight" : "submit", error.code)
+      1
+    rescue OptionParser::ParseError
+      emit_failure(@dry_run ? "preflight" : "submit", "invalid_options")
+      1
+    rescue StandardError
+      emit_failure(@dry_run ? "preflight" : "submit", "submission_failed")
+      1
+    end
+
+    private
+
+    def parse_options!
+      parser = OptionParser.new do |options|
+        options.on("--dry-run", "Validate and preflight without receipt changes or writes") { @dry_run = true }
+        options.on("--state-dir DIR", "Use a private receipt directory") { |directory| @state_dir = directory }
+      end
+      parser.parse!(@arguments)
+      raise InputError, "invalid_options" unless @arguments.empty?
+    end
+
+    def parse_and_validate_batch!
+      raw = JSON.parse(@input.read)
+      validate_batch!(raw)
+    rescue JSON::ParserError
+      raise InputError, "invalid_json"
+    end
+
+    def validate_batch!(batch)
+      require_hash_with_keys!(batch, TOP_LEVEL_KEYS, "invalid_batch_schema")
+      raise InputError, "invalid_batch_format" unless batch["format"] == FORMAT && batch["version"].is_a?(Integer) && batch["version"] == 1
+      raise InputError, "invalid_approval" unless [true, false].include?(batch["approved"])
+
+      from = valid_date!(batch["from"], "invalid_date_range")
+      to = valid_date!(batch["to"], "invalid_date_range")
+      raise InputError, "invalid_date_range" if to < from
+
+      policy = batch["policy"]
+      require_hash_with_keys!(policy, POLICY_KEYS, "invalid_batch_schema")
+      raise InputError, "invalid_policy" unless policy["mode"] == "concurrent-projects"
+      grace = policy["responseGraceMinutes"]
+      raise InputError, "invalid_policy" unless grace.is_a?(Integer) && grace >= 0
+
+      entries = batch["entries"]
+      raise InputError, "invalid_entries" unless entries.is_a?(Array) && !entries.empty?
+
+      seen_ids = {}
+      validated_entries = entries.map do |entry|
+        validate_entry!(entry, from, to, seen_ids)
+      end
+
+      {
+        approved: batch["approved"],
+        entries: validated_entries
+      }
+    end
+
+    def validate_entry!(entry, from, to, seen_ids)
+      require_hash_with_keys!(entry, ENTRY_KEYS, "invalid_entry_schema")
+      spent_date = valid_date!(entry["spentDate"], "invalid_entry_date")
+      raise InputError, "entry_date_out_of_range" unless spent_date.between?(from, to)
+
+      local_project = nonblank_string!(entry["localProject"], "invalid_entry_project")
+      id = nonblank_string!(entry["id"], "invalid_entry_id")
+      expected_id = identity_for(spent_date.iso8601, local_project)
+      raise InputError, "invalid_entry_identity" unless id == expected_id
+      raise InputError, "duplicate_identity" if seen_ids[id]
+      seen_ids[id] = true
+
+      candidate = positive_integer!(entry["candidateMilliseconds"], "invalid_duration")
+      milliseconds = positive_integer!(entry["milliseconds"], "invalid_duration")
+      raise InputError, "duration_exceeds_candidate" if milliseconds > candidate
+
+      nonnegative_integer!(entry["humanActiveMilliseconds"], "invalid_entry_schema")
+      nonnegative_integer!(entry["agentTurnMilliseconds"], "invalid_entry_schema")
+      nonnegative_integer!(entry["bridgedGapMilliseconds"], "invalid_entry_schema")
+      validate_string_array!(entry["sourceEntryIds"], "invalid_entry_schema", allow_empty: true)
+      validate_string_array!(entry["reviewReasons"], "invalid_entry_schema", allow_empty: true)
+      raise InputError, "entry_not_reviewed" unless entry["reviewed"] == true
+
+      project = nonblank_string!(entry["project"], "destination_required")
+      task = nonblank_string!(entry["task"], "destination_required")
+      notes = nonblank_string!(entry["notes"], "reviewed_notes_required")
+
+      {
+        id:,
+        spent_date: spent_date.iso8601,
+        local_project:,
+        project:,
+        task:,
+        milliseconds:,
+        notes:
+      }
+    end
+
+    def require_approval!(batch)
+      raise InputError, "batch_not_approved" unless @dry_run || batch[:approved]
+    end
+
+    def require_hash_with_keys!(value, keys, code)
+      raise InputError, code unless value.is_a?(Hash) && value.keys.sort == keys.sort
+    end
+
+    def nonblank_string!(value, code)
+      raise InputError, code unless value.is_a?(String) && !value.strip.empty?
+
+      value
+    end
+
+    def positive_integer!(value, code)
+      raise InputError, code unless value.is_a?(Integer) && value.positive?
+
+      value
+    end
+
+    def nonnegative_integer!(value, code)
+      raise InputError, code unless value.is_a?(Integer) && value >= 0
+
+      value
+    end
+
+    def validate_string_array!(value, code, allow_empty:)
+      raise InputError, code unless value.is_a?(Array) && (allow_empty || !value.empty?)
+      raise InputError, code unless value.all? { |item| item.is_a?(String) && !item.strip.empty? }
+    end
+
+    def valid_date!(value, code)
+      raise InputError, code unless value.is_a?(String)
+
+      date = Date.iso8601(value)
+      raise InputError, code unless date.iso8601 == value
+
+      date
+    rescue Date::Error
+      raise InputError, code
+    end
+
+    def identity_for(spent_date, local_project)
+      digest = Digest::SHA256.hexdigest(JSON.generate(["omp-worklog/v1", spent_date, local_project]))
+      "#{ID_PREFIX}#{digest}"
+    end
+
+    def account_id_from_environment
+      account_id = @environment["HARVEST_ACCOUNT_ID"]
+      raise InputError, "account_scope_required" unless account_id.is_a?(String) && !account_id.strip.empty?
+
+      account_id
+    end
+
+    def current_user_id(client)
+      user = request_object(client, :get, "/v2/users/me")
+      id = user["id"]
+      raise ProviderFailure, "invalid_current_user" unless valid_provider_id?(id)
+
+      id
+    end
+
+    def preflight_result(batch, client, user_id, receipt_context)
+      company = request_object(client, :get, "/v2/company")
+      timestamp_mode = company["wants_timestamp_timers"]
+      raise ProviderFailure, "invalid_company_response" unless [true, false].include?(timestamp_mode)
+      raise ProviderFailure, "timestamp_timer_mode_unsupported" if timestamp_mode
+
+      resolved_entries, resolution_results = resolve_entries(client, batch[:entries])
+      unless resolved_entries.length == batch[:entries].length
+        resolution_results.each do |result|
+          result["status"] = "not_submitted" if result["status"] == "ready"
+          result["reason"] ||= "batch_preflight_failed" if result["status"] == "not_submitted"
+        end
+        return build_result(@dry_run ? "preflight" : "submit", "blocked", resolution_results)
+      end
+
+      if duplicate_destination?(resolved_entries)
+        results = resolved_entries.map do |entry|
+          result_with_status(entry_result(entry, "conflict"), "conflict", "duplicate_destination")
+        end
+        return build_result(@dry_run ? "preflight" : "submit", "blocked", results)
+      end
+
+      remote_records = inspect_remote_entries(client, resolved_entries, user_id)
+      results = resolved_entries.map do |entry|
+        preflight_entry_result(entry, remote_records, receipt_context)
+      end
+
+      unless results.all? { |result| %w[ready already_filed].include?(result["status"]) }
+        results.each do |result|
+          result["status"] = "not_submitted" if result["status"] == "ready"
+          result["reason"] ||= "batch_preflight_failed" if result["status"] == "not_submitted"
+        end
+        status = results.any? { |result| result["status"] == "uncertain" } ? "uncertain" : "blocked"
+        return build_result(@dry_run ? "preflight" : "submit", status, results)
+      end
+
+      return build_result("preflight", "ready", results) if @dry_run
+
+      store, receipts = receipt_context
+      file_ready_entries(resolved_entries, results, store, receipts, client, user_id)
+    end
+
+    def request_object(client, method, path, params: {}, body: nil)
+      response = client.request(method, path, params:, body:)
+      raise ProviderFailure, "invalid_provider_response" unless response.is_a?(Hash)
+
+      response
+    rescue ProviderFailure
+      raise
+    rescue StandardError
+      raise ProviderFailure, "provider_request_failed"
+    end
+
+    def valid_provider_id?(value)
+      (value.is_a?(Integer) && value.positive?) || (value.is_a?(String) && value.match?(/\A[1-9]\d*\z/))
+    end
+
+    def resolve_entries(client, entries)
+      assignments = personal_assignments(client)
+      resolved_entries = []
+      results = entries.map do |entry|
+        matches = assignments.select do |assignment|
+          assignment[:project_name].casecmp?(entry[:project]) && assignment[:task_name].casecmp?(entry[:task])
+        end
+        if matches.empty?
+          result_with_status(entry_result(entry, "blocked"), "blocked", "destination_unmapped")
+        elsif matches.length > 1
+          result_with_status(entry_result(entry, "blocked"), "blocked", "destination_ambiguous")
+        else
+          assignment = matches.first
+          resolved_entries << entry.merge(project_id: assignment[:project_id], task_id: assignment[:task_id])
+          entry_result(entry, "ready")
+        end
+      end
+
+      [resolved_entries, results]
+    end
+
+    def personal_assignments(client)
+      assignments = paged_records(client, "/v2/users/me/project_assignments", "project_assignments", is_active: true)
+      assignments.filter_map do |project_assignment|
+        unless [true, false].include?(project_assignment["is_active"])
+          raise ProviderFailure, "invalid_assignment_response"
+        end
+        next unless project_assignment["is_active"]
+
+        project = project_assignment["project"]
+        raise ProviderFailure, "invalid_assignment_response" unless project.is_a?(Hash)
+        if project.key?("is_active") && ![true, false].include?(project["is_active"])
+          raise ProviderFailure, "invalid_assignment_response"
+        end
+        next if project["is_active"] == false
+        unless valid_provider_id?(project["id"]) && project["name"].is_a?(String) && !project["name"].strip.empty?
+          raise ProviderFailure, "invalid_assignment_response"
+        end
+
+        task_assignments = project_assignment["task_assignments"]
+        raise ProviderFailure, "invalid_assignment_response" unless task_assignments.is_a?(Array)
+
+        task_assignments.filter_map do |task_assignment|
+          raise ProviderFailure, "invalid_assignment_response" unless task_assignment.is_a?(Hash)
+          unless [true, false].include?(task_assignment["is_active"])
+            raise ProviderFailure, "invalid_assignment_response"
+          end
+          next unless task_assignment["is_active"]
+
+          task = task_assignment["task"]
+          raise ProviderFailure, "invalid_assignment_response" unless task.is_a?(Hash)
+          unless valid_provider_id?(task["id"]) && task["name"].is_a?(String) && !task["name"].strip.empty?
+            raise ProviderFailure, "invalid_assignment_response"
+          end
+
+          {
+            project_id: project["id"],
+            project_name: project["name"],
+            task_id: task["id"],
+            task_name: task["name"]
+          }
+        end
+      end.flatten
+    end
+
+    def paged_records(client, path, collection_key, **params)
+      records = []
+      page = 1
+      seen_pages = {}
+      seen_records = {}
+
+      loop do
+        raise ProviderFailure, "invalid_pagination" if seen_pages[page]
+        seen_pages[page] = true
+        response = request_object(client, :get, path, params: params.merge(page:, per_page: PER_PAGE))
+        page_records = response[collection_key]
+        raise ProviderFailure, "invalid_provider_response" unless page_records.is_a?(Array) && page_records.all? { |record| record.is_a?(Hash) }
+
+        page_records.each do |record|
+          signature = Digest::SHA256.hexdigest(JSON.generate(record))
+          raise ProviderFailure, "invalid_pagination" if seen_records[signature]
+
+          seen_records[signature] = true
+        end
+        records.concat(page_records)
+        next_page = response["next_page"]
+        # If the provider omits next_page, a full page still requires a conservative follow-up request.
+        if next_page.nil?
+          break if page_records.length < PER_PAGE
+
+          page += 1
+          next
+        end
+
+        next_page = parse_page_number(next_page)
+        raise ProviderFailure, "invalid_pagination" if seen_pages[next_page]
+
+        page = next_page
+      end
+
+      records
+    end
+
+    def parse_page_number(value)
+      page = if value.is_a?(Integer)
+               value
+             elsif value.is_a?(String) && value.match?(/\A[1-9]\d*\z/)
+               value.to_i
+             end
+      raise ProviderFailure, "invalid_pagination" unless page && page.positive?
+
+      page
+    end
+
+    def duplicate_destination?(entries)
+      destinations = entries.map { |entry| [entry[:spent_date], id_string(entry[:project_id]), id_string(entry[:task_id])] }
+      destinations.uniq.length != destinations.length
+    end
+
+    def inspect_remote_entries(client, entries, user_id)
+      by_reference = {}
+      entries.each do |entry|
+        matches = paged_records(
+          client,
+          "/v2/time_entries",
+          "time_entries",
+          user_id:, external_reference_id: entry[:id], from: entry[:spent_date], to: entry[:spent_date]
+        )
+        matches = current_user_records(matches, user_id)
+        validate_time_entry_records!(matches)
+        matches.each do |record|
+          raise ProviderFailure, "invalid_provider_response" unless record.dig("external_reference", "id") == entry[:id]
+        end
+        by_reference[entry[:id]] = matches
+      end
+
+      by_date = {}
+      entries.map { |entry| entry[:spent_date] }.uniq.each do |spent_date|
+        records = paged_records(
+          client,
+          "/v2/time_entries",
+          "time_entries",
+          user_id:, from: spent_date, to: spent_date
+        )
+        records = current_user_records(records, user_id)
+        validate_time_entry_records!(records)
+        by_date[spent_date] = records
+      end
+
+      { by_reference:, by_date: }
+    end
+
+    def current_user_records(records, user_id)
+      records.filter_map do |record|
+        record_user_id = record["user"].is_a?(Hash) ? record["user"]["id"] : nil
+        unless valid_provider_id?(record_user_id)
+          raise ProviderFailure, "invalid_provider_response"
+        end
+        if id_string(record_user_id) != id_string(user_id)
+          next
+        end
+
+        record
+      end
+    end
+
+    def validate_time_entry_records!(records)
+      records.each do |record|
+        unless valid_provider_id?(record["id"]) && record["project"].is_a?(Hash) &&
+            valid_provider_id?(record["project"]["id"]) && record["task"].is_a?(Hash) &&
+            valid_provider_id?(record["task"]["id"]) && record["spent_date"].is_a?(String)
+          raise ProviderFailure, "invalid_provider_response"
+        end
+
+        begin
+          date = Date.iso8601(record["spent_date"])
+        rescue Date::Error
+          raise ProviderFailure, "invalid_provider_response"
+        end
+        raise ProviderFailure, "invalid_provider_response" unless date.iso8601 == record["spent_date"]
+        raise ProviderFailure, "invalid_provider_response" unless record["hours"].nil? || record["hours"].is_a?(Numeric)
+        raise ProviderFailure, "invalid_provider_response" unless record["notes"].nil? || record["notes"].is_a?(String)
+
+        reference = record["external_reference"]
+        if !reference.nil? && (!reference.is_a?(Hash) || !reference["id"].is_a?(String) || reference["id"].empty?)
+          raise ProviderFailure, "invalid_provider_response"
+        end
+      end
+    end
+
+    def preflight_entry_result(entry, remote_records, receipt_context)
+      result = entry_result(entry, "ready")
+      matching_records = remote_records[:by_reference].fetch(entry[:id])
+      if matching_records.any?
+        if matching_records.length != 1
+          return result_with_status(result, "conflict", "duplicate_external_reference")
+        end
+
+        record = matching_records.first
+        return result_with_status(result, "already_filed", nil, record["id"]) if exact_remote_match?(entry, record)
+
+        return result_with_status(result, "conflict", "external_reference_content_conflict")
+      end
+
+      destination_records = remote_records[:by_date].fetch(entry[:spent_date]).select do |record|
+        id_string(record.dig("project", "id")) == id_string(entry[:project_id]) &&
+          id_string(record.dig("task", "id")) == id_string(entry[:task_id])
+      end
+      if destination_records.any?
+        reason = destination_records.any? { |record| record["is_locked"] == true || record["is_running"] == true } ?
+          "locked_or_running_entry" : "existing_entry"
+        return result_with_status(result, "blocked", reason)
+      end
+
+      receipt = if receipt_context
+                  receipt_context.last[entry[:id]]
+                end
+      if receipt && %w[pending uncertain submitted].include?(receipt["status"])
+        unless receipt["fingerprint"] == fingerprint(entry)
+          return result_with_status(result, "conflict", "receipt_content_conflict")
+        end
+
+        return result_with_status(result, "uncertain", "remote_entry_not_found")
+      end
+
+      result
+    end
+
+    def exact_remote_match?(entry, record)
+      valid_provider_id?(record["id"]) &&
+        record["spent_date"] == entry[:spent_date] &&
+        id_string(record.dig("project", "id")) == id_string(entry[:project_id]) &&
+        id_string(record.dig("task", "id")) == id_string(entry[:task_id]) &&
+        numeric_hours?(record["hours"], entry[:milliseconds]) &&
+        record["notes"] == entry[:notes] && record["is_running"] == false
+    end
+
+    def numeric_hours?(hours, milliseconds)
+      hours.is_a?(Numeric) && hours == milliseconds / 3_600_000.0
+    end
+
+    def id_string(value)
+      value.nil? ? "" : value.to_s
+    end
+
+    def fingerprint(entry)
+      canonical = [
+        entry[:id], entry[:spent_date], entry[:project_id], entry[:task_id],
+        entry[:milliseconds], entry[:notes]
+      ]
+      Digest::SHA256.hexdigest(JSON.generate(canonical))
+    end
+
+    def entry_result(entry, status)
+      {
+        "id" => entry[:id],
+        "spentDate" => entry[:spent_date],
+        "localProject" => entry[:local_project],
+        "status" => status
+      }
+    end
+
+    def result_with_status(result, status, reason, harvest_entry_id = nil)
+      result["status"] = status
+      result["reason"] = reason if reason
+      result["harvestEntryId"] = harvest_entry_id if harvest_entry_id
+      result
+    end
+
+    def file_ready_entries(entries, results, store, receipts, client, user_id)
+      entries.each_with_index do |entry, index|
+        if results[index]["status"] == "already_filed"
+          receipts[entry[:id]] = receipt_for(entry, "submitted", results[index]["harvestEntryId"])
+        end
+      end
+      store.save!(receipts) if results.any? { |result| result["status"] == "already_filed" }
+
+      entries.each_with_index do |entry, index|
+        next unless results[index]["status"] == "ready"
+
+        receipts[entry[:id]] = receipt_for(entry, "pending")
+        store.save!(receipts)
+        begin
+          response = client.request(
+            :post,
+            "/v2/time_entries",
+            body: {
+              user_id:,
+              project_id: entry[:project_id],
+              task_id: entry[:task_id],
+              spent_date: entry[:spent_date],
+              hours: entry[:milliseconds] / 3_600_000.0,
+              notes: entry[:notes],
+              external_reference: { id: entry[:id] }
+            }
+          )
+          harvest_entry_id = response.is_a?(Hash) ? response["id"] : nil
+          unless valid_provider_id?(harvest_entry_id)
+            receipts[entry[:id]] = receipt_for(entry, "uncertain")
+            store.save!(receipts)
+            result_with_status(results[index], "uncertain", "invalid_create_response")
+            mark_not_submitted(results, index + 1)
+            return build_result("submit", "uncertain", results)
+          end
+
+          receipts[entry[:id]] = receipt_for(entry, "submitted", harvest_entry_id)
+          store.save!(receipts)
+          result_with_status(results[index], "created", nil, harvest_entry_id)
+        rescue Marlens::HarvestApiV2::Error => error
+          if %w[400 401 403 404 422 429].include?(error.status.to_s)
+            receipts[entry[:id]] = receipt_for(entry, "rejected")
+            store.save!(receipts)
+            result_with_status(results[index], "blocked", "provider_rejected")
+          else
+            receipts[entry[:id]] = receipt_for(entry, "uncertain")
+            store.save!(receipts)
+            result_with_status(results[index], "uncertain", "create_outcome_unknown")
+          end
+          mark_not_submitted(results, index + 1)
+          return submission_result(results)
+        rescue StandardError
+          receipts[entry[:id]] = receipt_for(entry, "uncertain")
+          begin
+            store.save!(receipts)
+          rescue StandardError
+            # The pending receipt was durable before the request.
+          end
+          result_with_status(results[index], "uncertain", "create_outcome_unknown")
+          mark_not_submitted(results, index + 1)
+          return build_result("submit", "uncertain", results)
+        end
+      end
+
+      build_result("submit", "complete", results)
+    end
+
+    def receipt_for(entry, status, harvest_entry_id = nil)
+      receipt = { "fingerprint" => fingerprint(entry), "status" => status }
+      receipt["harvestEntryId"] = harvest_entry_id if harvest_entry_id
+      receipt
+    end
+
+    def mark_not_submitted(results, start_index)
+      results.each_with_index do |result, index|
+        next if index < start_index || result["status"] != "ready"
+
+        result["status"] = "not_submitted"
+        result["reason"] = "earlier_create_failed"
+      end
+    end
+
+    def submission_result(results)
+      return build_result("submit", "uncertain", results) if results.any? { |result| result["status"] == "uncertain" }
+
+      succeeded = results.any? { |result| %w[created already_filed].include?(result["status"]) }
+      build_result("submit", succeeded ? "partial" : "blocked", results)
+    end
+
+    def build_result(mode, status, results)
+      {
+        "format" => RESULT_FORMAT,
+        "version" => 1,
+        "mode" => mode,
+        "status" => status,
+        "results" => results
+      }
+    end
+
+    def successful_result?(result)
+      %w[ready complete].include?(result["status"])
+    end
+
+    def emit_result(result)
+      @output.puts JSON.generate(result)
+    end
+
+    def emit_failure(mode, reason)
+      @error.puts "Error: #{reason}"
+      emit_result(build_result(mode, "blocked", []).merge("reason" => reason))
+    end
+
+    def receipt_directory
+      @state_dir || File.join(Dir.home, ".omp", "worklog", "submissions")
+    end
+
+    class ReceiptStore
+      def initialize(directory, account_id, user_id)
+        @directory = directory
+        @scope = Digest::SHA256.hexdigest(JSON.generate([account_id, user_id]))
+        @receipt_path = File.join(directory, "#{@scope}.json")
+        @lock_path = File.join(directory, "#{@scope}.lock")
+      end
+
+      def read_only
+        return {} unless File.exist?(@directory)
+        raise ProviderFailure, "unsafe_receipt_directory" if File.lstat(@directory).symlink?
+
+        load_receipts
+      end
+
+      def with_lock
+        FileUtils.mkdir_p(@directory, mode: 0o700)
+        raise ProviderFailure, "unsafe_receipt_directory" if File.lstat(@directory).symlink?
+
+        File.chmod(0o700, @directory)
+        File.open(@lock_path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+          begin
+            raise ProviderFailure, "unsafe_receipt_lock" unless lock.stat.file?
+
+            File.chmod(0o600, @lock_path)
+            File.chmod(0o600, @receipt_path) if File.exist?(@receipt_path) && !File.lstat(@receipt_path).symlink?
+            lock.flock(File::LOCK_EX)
+            yield load_receipts
+          ensure
+            lock.flock(File::LOCK_UN)
+          end
+        end
+      rescue ProviderFailure
+        raise
+      rescue StandardError
+        raise ProviderFailure, "receipt_storage_failed"
+      end
+
+      def save!(receipts)
+        Tempfile.create([".receipt-", ".tmp"], @directory, mode: 0o600) do |temporary|
+          temporary.chmod(0o600)
+          temporary.write(JSON.generate({ "format" => RECEIPT_FORMAT, "version" => 1, "entries" => receipts }))
+          temporary.flush
+          temporary.fsync
+          File.rename(temporary.path, @receipt_path)
+          File.open(@directory, File::RDONLY) { |directory| directory.fsync }
+        end
+      rescue StandardError
+        raise ProviderFailure, "receipt_storage_failed"
+      end
+
+      private
+
+      def load_receipts
+        return {} unless File.exist?(@receipt_path)
+
+        raise ProviderFailure, "unsafe_receipt_file" if File.lstat(@receipt_path).symlink?
+        document = File.open(@receipt_path, File::RDONLY | File::NOFOLLOW, &:read)
+        data = JSON.parse(document)
+        unless data.is_a?(Hash) && data["format"] == RECEIPT_FORMAT && data["version"] == 1 && data["entries"].is_a?(Hash)
+          raise ProviderFailure, "invalid_receipt_state"
+        end
+
+        data["entries"].each_value do |receipt|
+          unless receipt.is_a?(Hash) && %w[pending uncertain submitted rejected].include?(receipt["status"]) &&
+              receipt["fingerprint"].is_a?(String)
+            raise ProviderFailure, "invalid_receipt_state"
+          end
+        end
+        data["entries"]
+      rescue JSON::ParserError
+        raise ProviderFailure, "invalid_receipt_state"
+      end
+    end
+  end
+end

data/lib/omp_worklog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmpWorklog
-  VERSION = "0.14.6"
+  VERSION = "0.15.0"
 end

data/lib/omp_worklog.rb

@@ -28,13 +28,15 @@ module OmpWorklog
   class Error < StandardError; end
 
   class CLI
-    def self.run(arguments, output: $stdout, error: $stderr, client: nil)
+    def self.run(arguments, output: $stdout, error: $stderr, client: nil, input: $stdin)
       command, *command_arguments = arguments
       case command
       when "time-off"
         TimeOffCLI.run(command_arguments, output:, error:, client:)
       when "work-entry"
         WorkEntryCLI.run(command_arguments, output:, error:, client:)
+      when "work-entry-batch"
+        BatchCLI.run(command_arguments, input:, output:, error:, client:)
       when "-h", "--help"
         output.puts usage
         0
@@ -42,7 +44,7 @@ module OmpWorklog
         output.puts VERSION
         0
       else
-        error.puts "Error: choose time-off or work-entry"
+        error.puts "Error: choose time-off, work-entry, or work-entry-batch"
         error.puts usage
         1
       end
@@ -55,10 +57,12 @@ module OmpWorklog
           omp-worklog time-off FROM TO --project-id ID --task-id ID [options]
           omp-worklog work-entry DATE --project NAME --task NAME --hours HOURS --notes NOTES [options]
           omp-worklog work-entry DATE --project-id ID --task-id ID --hours HOURS --notes NOTES [options]
+          omp-worklog work-entry-batch [--dry-run] [--state-dir DIR] < review-batch.json
 
         Commands:
-          time-off    Create one entry per local business day in a date range.
-          work-entry  Create one reviewed ordinary-work entry.
+          time-off          Create one entry per local business day in a date range.
+          work-entry        Create one reviewed ordinary-work entry.
+          work-entry-batch  Preflight and submit one approved reviewed batch.
       USAGE
     end
   end
@@ -180,3 +184,4 @@ module OmpWorklog
 end
 
 require "omp_worklog/work_entry_cli"
+require "omp_worklog/batch_cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omp-worklog
 version: !ruby/object:Gem::Version
-  version: 0.14.6
+  version: 0.15.0
 platform: ruby
 authors:
 - Marlen Brunner
@@ -65,6 +65,7 @@ files:
 - bin/release-plugin
 - bin/verify-plugin-release
 - lib/omp_worklog.rb
+- lib/omp_worklog/batch_cli.rb
 - lib/omp_worklog/version.rb
 - lib/omp_worklog/work_entry_cli.rb
 - omp-worklog.rb
@@ -91,5 +92,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: OMP Project Time work logs with an optional manual Harvest destination.
+summary: Concurrent-project work logs with reviewed, safe Harvest batch filing.
 test_files: []