carson 3.27.0 → 3.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e71c18b520bc6869f6f22cff8593d59b7e4d38a58b7c9f7648d75252fdd8691c
-  data.tar.gz: 468b1b132620b3844ccd5df01907c149ddce5bf987bf2aa4fee6a17f3301cea7
+  metadata.gz: 1551ba09ad6dd7d0d2f0341f75e764d41334085b8e27015d7dc4d4e09007a25a
+  data.tar.gz: 9abc7ea81d920afd602f444c534731e8b5b3cf2b8762da40a9ef411d9d984845
 SHA512:
-  metadata.gz: 6a3842a3fdb48ede44c4def41b1533ae43f68b5267a8d1280f1cdf7685b161406f58365002e20b34bb4dfa5a9fc2e788a970cf6c406dd877087844197114148d
-  data.tar.gz: 8ee70fb5f5f06bfc417ae39634f9277a07ca5aaa867a57b14960987a12cbe66a44ea193fc167831645025cd573d599f8cf385e8849c2a40d94ff0c6c43eb5967
+  metadata.gz: 402d821608dcb4b5a448b3c6a1d9b7cf3de3415b6ab87323e035623f118d0a91e91ce50405bb25d4d608324682eff6ccdddfd7e4c13319b8e339dcc46e699dd0
+  data.tar.gz: 184128f03321ef5e59c6168a1fcea4c9a223f7d040aaeafa61661de7c0fad77fbd79549d143021c90db25cb7217d53c29eb18da46882744eaf0d85a705604eb8

data/API.md

@@ -157,7 +157,7 @@ Environment overrides:
 - `agent.codex` / `agent.claude`: provider-specific options (reserved).
 - `check_wait`: seconds to wait for CI checks before classifying (default: `30`).
 - `merge.method`: `"squash"` only in governed mode.
-- `state_path`: JSON file path for active deliveries and revisions.
+- `state_path`: JSON ledger path for active deliveries and revisions. Legacy SQLite ledgers are imported automatically on first read; explicit legacy `.sqlite3` paths keep working after import.
 
 `template` schema:
 

data/MANUAL.md

@@ -66,12 +66,12 @@ on:
 
 jobs:
   governance:
-    uses: wanghailei/carson/.github/workflows/carson_policy.yml@v1.0.0
+    uses: wanghailei/carson/.github/workflows/carson_policy.yml@v3.27.1
     secrets:
       CARSON_READ_TOKEN: ${{ secrets.CARSON_READ_TOKEN }}
     with:
-      carson_ref: "v1.0.0"
-      carson_version: "1.0.0"
+      carson_ref: "v3.27.1"
+      carson_version: "3.27.1"
       rubocop_version: "1.81.0"
 ```
 

data/RELEASE.md

@@ -5,6 +5,18 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 3.27.1
+
+### What changed
+
+- **JSON ledger preserves legacy state and FIFO ordering** — legacy SQLite ledgers now import automatically into the JSON store on first read, same branch/head deliveries collapse across repo-path aliases, and queue order stays first-in-first-out even when multiple deliveries share the same timestamp.
+- **sqlite3 support restored for migration** — `carson.gemspec` depends on `sqlite3` again so Carson can import legacy SQLite ledgers, and CI installs the gem before running unit tests.
+- **Script Ruby guards now follow the gem contract** — `script/ci_smoke.sh` and `script/install_global_carson.sh` read the minimum supported Ruby version from `carson.gemspec` instead of hard-coding it, so smoke checks and installer behaviour stay aligned with the published gem.
+
+### Migration
+
+- Existing SQLite ledgers are imported automatically on first read. Explicit legacy `.sqlite3` paths keep working after import.
+
 ## 3.27.0
 
 ### What changed
@@ -27,7 +39,9 @@ Release-note scope rule:
 - **Govern now finds worktree-created deliveries** — `repository_record` stored the worktree CWD as `repo_path` in the ledger, but `govern` looked up deliveries by the main tree path from config. The SQL query never matched, so `carson govern` always reported "no active deliveries" for worktree-created PRs. Now `repository_record` uses `main_worktree_root` so the ledger key is always the canonical main tree path. Also fixed the govern fallback path, `reconcile_delivery!`, `housekeep_repo!`, and `review_evidence` for the same mismatch.
 - **Status shows canonical repository name** — `carson status` from a worktree displayed the worktree folder name (e.g. `feature-branch`) as `Repository:` instead of the actual repository name. Now correctly shows the canonical name.
 
-### No migration required
+### Migration note
+
+- Existing SQLite ledgers are imported automatically on first read. No manual cleanup is required before upgrading.
 
 ## 3.23.3
 

data/VERSION

@@ -1 +1 @@
-3.27.0
+3.27.1

data/carson.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
 	spec.bindir = "exe"
 	spec.executables = [ "carson" ]
 	spec.require_paths = [ "lib" ]
+	spec.add_dependency "sqlite3", ">= 1.3", "< 3"
 	spec.files = Dir.glob( "{lib,exe,templates,hooks}/**/*", File::FNM_DOTMATCH ).select { |path| File.file?( path ) } + [
 		".github/workflows/carson_policy.yml",
 		"README.md",

data/lib/carson/ledger.rb

@@ -7,10 +7,12 @@ module Carson
 	class Ledger
 		UNSET = Object.new
 		ACTIVE_DELIVERY_STATES = Delivery::ACTIVE_STATES
+		SQLITE_HEADER = "SQLite format 3\0".b.freeze
 
 		def initialize( path: )
 			@path = File.expand_path( path )
 			FileUtils.mkdir_p( File.dirname( @path ) )
+			migrate_legacy_state_if_needed!
 		end
 
 		attr_reader :path
@@ -20,23 +22,22 @@ module Carson
 			timestamp = now_utc
 
 			with_state do |state|
+				repo_paths = repo_identity_paths( repo_path: repository.path )
+				matches = matching_deliveries(
+					state: state,
+					repo_paths: repo_paths,
+					branch_name: branch_name,
+					head: head
+				)
 				key = delivery_key( repo_path: repository.path, branch_name: branch_name, head: head )
-				existing = state[ "deliveries" ][ key ]
-
-				if existing
-					existing[ "repo_path" ] = repository.path
-					existing[ "worktree_path" ] = worktree_path
-					existing[ "status" ] = status
-					existing[ "pr_number" ] = pr_number
-					existing[ "pr_url" ] = pr_url
-					existing[ "cause" ] = cause
-					existing[ "summary" ] = summary
-					existing[ "updated_at" ] = timestamp
-					return build_delivery( key: key, data: existing, repository: repository )
-				end
+				sequence = matches.map { |_existing_key, data| delivery_sequence( data: data ) }.compact.min
+				created_at = matches.map { |_existing_key, data| data.fetch( "created_at", "" ).to_s }.reject( &:empty? ).min || timestamp
+				revisions = merged_revisions( entries: matches )
+				matches.each { |existing_key, _data| state[ "deliveries" ].delete( existing_key ) }
 
 				supersede_branch!( state: state, repo_path: repository.path, branch_name: branch_name, timestamp: timestamp )
 				state[ "deliveries" ][ key ] = {
+					"sequence" => sequence || next_delivery_sequence!( state: state ),
 					"repo_path" => repository.path,
 					"branch_name" => branch_name,
 					"head" => head,
@@ -46,11 +47,11 @@ module Carson
 					"pr_url" => pr_url,
 					"cause" => cause,
 					"summary" => summary,
-					"created_at" => timestamp,
+					"created_at" => created_at,
 					"updated_at" => timestamp,
 					"integrated_at" => nil,
 					"superseded_at" => nil,
-					"revisions" => []
+					"revisions" => revisions
 				}
 				build_delivery( key: key, data: state[ "deliveries" ][ key ], repository: repository )
 			end
@@ -69,7 +70,7 @@ module Carson
 
 			return nil if candidates.empty?
 
-			key, data = candidates.max_by { |k, d| [ d[ "updated_at" ].to_s, k ] }
+			key, data = candidates.max_by { |k, d| [ d[ "updated_at" ].to_s, delivery_sequence( data: d ), k ] }
 			build_delivery( key: key, data: data )
 		end
 
@@ -80,7 +81,7 @@ module Carson
 
 			state[ "deliveries" ]
 				.select { |_key, data| repo_paths.include?( data[ "repo_path" ] ) && ACTIVE_DELIVERY_STATES.include?( data[ "status" ] ) }
-				.sort_by { |key, data| [ data[ "created_at" ].to_s, key ] }
+				.sort_by { |key, data| [ delivery_sequence( data: data ), key ] }
 				.map { |key, data| build_delivery( key: key, data: data ) }
 		end
 
@@ -95,7 +96,7 @@ module Carson
 						data[ "status" ] == "integrated" &&
 						!data[ "worktree_path" ].to_s.strip.empty?
 				end
-				.sort_by { |key, data| [ data[ "integrated_at" ].to_s, data[ "updated_at" ].to_s, key ] }
+				.sort_by { |key, data| [ data[ "integrated_at" ].to_s, delivery_sequence( data: data ), key ] }
 				.map { |key, data| build_delivery( key: key, data: data ) }
 		end
 
@@ -112,8 +113,7 @@ module Carson
 			superseded_at: UNSET
 		)
 			with_state do |state|
-				data = state[ "deliveries" ][ delivery.key ]
-				raise "delivery not found: #{delivery.key}" unless data
+				key, data = resolve_delivery_entry( state: state, delivery: delivery )
 
 				data[ "status" ] = status unless status.equal?( UNSET )
 				data[ "pr_number" ] = pr_number unless pr_number.equal?( UNSET )
@@ -125,7 +125,7 @@ module Carson
 				data[ "superseded_at" ] = superseded_at unless superseded_at.equal?( UNSET )
 				data[ "updated_at" ] = now_utc
 
-				build_delivery( key: delivery.key, data: data, repository: delivery.repository )
+				build_delivery( key: key, data: data, repository: delivery.repository )
 			end
 		end
 
@@ -134,8 +134,7 @@ module Carson
 			timestamp = now_utc
 
 			with_state do |state|
-				data = state[ "deliveries" ][ delivery.key ]
-				raise "delivery not found: #{delivery.key}" unless data
+				_key, data = resolve_delivery_entry( state: state, delivery: delivery )
 
 				revisions = data[ "revisions" ] ||= []
 				next_number = ( revisions.map { |r| r[ "number" ].to_i }.max || 0 ) + 1
@@ -166,11 +165,7 @@ module Carson
 
 		# Acquires file lock, loads state, yields for mutation, saves atomically, releases lock.
 		def with_state
-			lock_path = "#{path}.lock"
-			FileUtils.mkdir_p( File.dirname( lock_path ) )
-			FileUtils.touch( lock_path )
-
-			File.open( lock_path, File::RDWR | File::CREAT ) do |lock_file|
+			with_state_lock do |lock_file|
 				lock_file.flock( File::LOCK_EX )
 				state = load_state
 				result = yield state
@@ -180,21 +175,22 @@ module Carson
 		end
 
 		def load_state
-		return { "deliveries" => {}, "recovery_events" => [] } unless File.exist?( path )
+			return { "deliveries" => {}, "recovery_events" => [] } unless File.exist?( path )
 
-			raw = File.read( path )
+			raw = File.binread( path )
 			return { "deliveries" => {}, "recovery_events" => [] } if raw.strip.empty?
 
 			parsed = JSON.parse( raw )
 			raise "state file must contain a JSON object at #{path}" unless parsed.is_a?( Hash )
 			parsed[ "deliveries" ] ||= {}
-		parsed[ "recovery_events" ] ||= []
+			normalise_state!( state: parsed )
 			parsed
-		rescue JSON::ParserError => exception
+		rescue JSON::ParserError, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError => exception
 			raise "invalid JSON in state file #{path}: #{exception.message}"
 		end
 
 		def save_state!( state )
+			normalise_state!( state: state )
 			tmp_path = "#{path}.tmp"
 			File.write( tmp_path, JSON.pretty_generate( state ) + "\n" )
 			File.rename( tmp_path, path )
@@ -242,6 +238,228 @@ module Carson
 			)
 		end
 
+		def migrate_legacy_state_if_needed!
+			with_state_lock do |lock_file|
+				lock_file.flock( File::LOCK_EX )
+				source_path = legacy_sqlite_source_path
+				next unless source_path
+
+				state = load_legacy_sqlite_state( path: source_path )
+				save_state!( state )
+			end
+		end
+
+		def with_state_lock
+			lock_path = "#{path}.lock"
+			FileUtils.mkdir_p( File.dirname( lock_path ) )
+			FileUtils.touch( lock_path )
+
+			File.open( lock_path, File::RDWR | File::CREAT ) do |lock_file|
+				yield lock_file
+			end
+		end
+
+		def legacy_sqlite_source_path
+			return nil unless state_path_requires_migration?
+			return path if sqlite_database_file?( path: path )
+
+			legacy_path = legacy_state_path
+			return nil unless legacy_path
+			return legacy_path if sqlite_database_file?( path: legacy_path )
+
+			nil
+		end
+
+		def state_path_requires_migration?
+			return true if sqlite_database_file?( path: path )
+			return false if File.exist?( path )
+			!legacy_state_path.nil?
+		end
+
+		def legacy_state_path
+			return nil unless path.end_with?( ".json" )
+			path.sub( /\.json\z/, ".sqlite3" )
+		end
+
+		def sqlite_database_file?( path: )
+			return false unless File.file?( path )
+			File.binread( path, SQLITE_HEADER.bytesize ) == SQLITE_HEADER
+		rescue StandardError
+			false
+		end
+
+		def load_legacy_sqlite_state( path: )
+			begin
+				require "sqlite3"
+			rescue LoadError => exception
+				raise "legacy SQLite ledger found at #{path}, but sqlite3 support is unavailable: #{exception.message}"
+			end
+
+			database = open_legacy_sqlite_database( path: path )
+			deliveries = database.execute( "SELECT * FROM deliveries ORDER BY id ASC" )
+			revisions_by_delivery = database.execute(
+				"SELECT * FROM revisions ORDER BY delivery_id ASC, number ASC, id ASC"
+			).group_by { |row| row.fetch( "delivery_id" ) }
+
+			state = {
+				"deliveries" => {},
+				"recovery_events" => [],
+				"next_sequence" => 1
+			}
+			deliveries.each do |row|
+				key = delivery_key(
+					repo_path: row.fetch( "repo_path" ),
+					branch_name: row.fetch( "branch_name" ),
+					head: row.fetch( "head" )
+				)
+				state[ "deliveries" ][ key ] = {
+					"sequence" => row.fetch( "id" ).to_i,
+					"repo_path" => row.fetch( "repo_path" ),
+					"branch_name" => row.fetch( "branch_name" ),
+					"head" => row.fetch( "head" ),
+					"worktree_path" => row.fetch( "worktree_path" ),
+					"status" => row.fetch( "status" ),
+					"pr_number" => row.fetch( "pr_number" ),
+					"pr_url" => row.fetch( "pr_url" ),
+					"cause" => row.fetch( "cause" ),
+					"summary" => row.fetch( "summary" ),
+					"created_at" => row.fetch( "created_at" ),
+					"updated_at" => row.fetch( "updated_at" ),
+					"integrated_at" => row.fetch( "integrated_at" ),
+					"superseded_at" => row.fetch( "superseded_at" ),
+					"revisions" => Array( revisions_by_delivery[ row.fetch( "id" ) ] ).map do |revision|
+						{
+							"number" => revision.fetch( "number" ).to_i,
+							"cause" => revision.fetch( "cause" ),
+							"provider" => revision.fetch( "provider" ),
+							"status" => revision.fetch( "status" ),
+							"started_at" => revision.fetch( "started_at" ),
+							"finished_at" => revision.fetch( "finished_at" ),
+							"summary" => revision.fetch( "summary" )
+						}
+					end
+				}
+			end
+			normalise_state!( state: state )
+			state
+		ensure
+			database&.close
+		end
+
+		def open_legacy_sqlite_database( path: )
+			database = SQLite3::Database.new( "file:#{path}?immutable=1", readonly: true, uri: true )
+			database.results_as_hash = true
+			database.busy_timeout = 5_000
+			database
+		rescue SQLite3::CantOpenException
+			database&.close
+			database = SQLite3::Database.new( path, readonly: true )
+			database.results_as_hash = true
+			database.busy_timeout = 5_000
+			database
+		end
+
+		def normalise_state!( state: )
+			deliveries = state[ "deliveries" ]
+			raise "state file must contain a JSON object at #{path}" unless deliveries.is_a?( Hash )
+			state[ "recovery_events" ] = Array( state[ "recovery_events" ] )
+
+			sequence_counts = Hash.new( 0 )
+			deliveries.each_value do |data|
+				data[ "revisions" ] = Array( data[ "revisions" ] )
+				sequence = integer_or_nil( value: data[ "sequence" ] )
+				sequence_counts[ sequence ] += 1 unless sequence.nil? || sequence <= 0
+			end
+
+			max_sequence = sequence_counts.keys.max.to_i
+			next_sequence = max_sequence + 1
+			deliveries.keys.sort_by { |key| [ deliveries.fetch( key ).fetch( "created_at", "" ).to_s, key ] }.each do |key|
+				data = deliveries.fetch( key )
+				sequence = integer_or_nil( value: data[ "sequence" ] )
+				if sequence.nil? || sequence <= 0 || sequence_counts[ sequence ] > 1
+					sequence = next_sequence
+					next_sequence += 1
+				end
+				data[ "sequence" ] = sequence
+			end
+
+			recorded_next = integer_or_nil( value: state[ "next_sequence" ] ) || 1
+			state[ "next_sequence" ] = [ recorded_next, next_sequence ].max
+		end
+
+		def next_delivery_sequence!( state: )
+			sequence = integer_or_nil( value: state[ "next_sequence" ] ) || 1
+			state[ "next_sequence" ] = sequence + 1
+			sequence
+		end
+
+		def integer_or_nil( value: )
+			Integer( value )
+		rescue ArgumentError, TypeError
+			nil
+		end
+
+		def delivery_sequence( data: )
+			integer_or_nil( value: data[ "sequence" ] ) || 0
+		end
+
+		def matching_deliveries( state:, repo_paths:, branch_name:, head: UNSET )
+			state[ "deliveries" ].select do |_key, data|
+				next false unless repo_paths.include?( data[ "repo_path" ] )
+				next false unless data[ "branch_name" ] == branch_name
+				next false unless head.equal?( UNSET ) || data[ "head" ] == head
+
+				true
+			end
+		end
+
+		def resolve_delivery_entry( state:, delivery: )
+			data = state[ "deliveries" ][ delivery.key ]
+			return [ delivery.key, data ] if data
+
+			repo_paths = repo_identity_paths( repo_path: delivery.repo_path )
+			match = matching_deliveries(
+				state: state,
+				repo_paths: repo_paths,
+				branch_name: delivery.branch,
+				head: delivery.head
+			).max_by { |key, row| [ row[ "updated_at" ].to_s, delivery_sequence( data: row ), key ] }
+			raise "delivery not found: #{delivery.key}" unless match
+
+			match
+		end
+
+		def merged_revisions( entries: )
+			entries
+				.flat_map { |_key, data| Array( data[ "revisions" ] ) }
+				.map do |revision|
+					{
+						"number" => revision.fetch( "number", 0 ).to_i,
+						"cause" => revision[ "cause" ],
+						"provider" => revision[ "provider" ],
+						"status" => revision[ "status" ],
+						"started_at" => revision[ "started_at" ],
+						"finished_at" => revision[ "finished_at" ],
+						"summary" => revision[ "summary" ]
+					}
+				end
+				.uniq do |revision|
+					[
+						revision[ "cause" ],
+						revision[ "provider" ],
+						revision[ "status" ],
+						revision[ "started_at" ],
+						revision[ "finished_at" ],
+						revision[ "summary" ]
+					]
+				end
+				.sort_by { |revision| [ revision.fetch( "started_at", "" ).to_s, revision.fetch( "number", 0 ).to_i ] }
+				.each_with_index
+				.map do |revision, index|
+					revision.merge( "number" => index + 1 )
+				end
+		end
+
 		def supersede_branch!( state:, repo_path:, branch_name:, timestamp: )
 			repo_paths = repo_identity_paths( repo_path: repo_path )
 			state[ "deliveries" ].each do |_key, data|
@@ -294,7 +512,7 @@ module Carson
 		end
 
 		def now_utc
-			Time.now.utc.iso8601
+			Time.now.utc.iso8601( 6 )
 		end
 
 		def record_recovery_event( repository:, branch_name:, pr_number:, pr_url:, check_name:, default_branch:, default_branch_sha:, pr_sha:, actor:, merge_method:, status:, summary: )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.27.0
+  version: 3.27.1
 platform: ruby
 authors:
 - Hailei Wang
@@ -10,7 +10,27 @@ authors:
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 description: 'Carson is an autonomous git strategist and repositories governor that
   lives outside the repositories it governs — no Carson-owned artefacts in your repo.
   As strategist, Carson knows when to branch, how to isolate concurrent work, and