ctx_driver 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4568b50606564c6f379c1110bd52c00566cfc7868f59f4253e38f675e2cf11db
-  data.tar.gz: 32e3dc04f8ee25ec7c21dd6c52beb607f0a51ecf2e80b4d39a30b125a28f70d4
+  metadata.gz: cbf951e5ac7ad8b23db6a73c445dc84447409327d60ec5270198aba4bc7f328f
+  data.tar.gz: 495dddd8a7c80bd79db88ea28e4c05cc16903f284f035e283d7c999b3536846f
 SHA512:
-  metadata.gz: af9f05c3a2fa5f0f9324641a2d81dc95a0488ab0ff7fccc50ec1302852f04e75b074015c34390f27ce7c66aa9a9bfb8ced2916f29c2878656929d85c6ea35cf8
-  data.tar.gz: 8527273f5407104dfa36c6414d0b65a5a2ecc9991a1572c408044b435fa8792346f4c923fabda6ee2dd365df6a1bc793a2cce3fa325d98e155282df8e63d66e2
+  metadata.gz: c00293dbe1c84597086e608f24c0cf7bf33b4e4cab329b62021501217afdb682035d59cdd66515c815860f7608038638778e5e69844f0d30358ee6d03bab17fb
+  data.tar.gz: 7d01f6e2c457b46d1889e34c7a79c05ab6d50d23624fddc46dd754abbd00adcab9f7b0b50fb9cb34249b2d428665915f5135a3b6651da138e409f7e9a0bff538

data/CHANGELOG.md

@@ -4,6 +4,10 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 0.5.0 (2026-10-30)
+
+- Introduce immutable `Source` values with validated digest/byte pairs, timestamps and domain context. Retain acquired digests on clock failure. Share single-command receipt validation between reads and writes; borrowed configuration writes never reconnect.
+
 ## 0.4.0 (2026-10-29)
 
 - Use the parser command contract for borrowed-session reads; preserve single-command identity and stop-after-desynchronization behavior.

data/README.md

@@ -123,3 +123,7 @@ MIT. See [LICENSE](LICENSE).
 Receipt protocol: each completed step is `{ command: String }` with exactly the requested command bytes. Success requires one step; failure permits zero or one. Opaque placeholder steps are no longer accepted. Missing or mismatched identity yields `invalid_command_result` and stops later queries while retaining raw fingerprints. Session adapts native net-connector steps automatically.
 
 本次使用 ctx_parser 0.4 系列契约；`Result` 新增 `covered_scopes`，单行命令统一由 `CtxParser::Commands.command_text` 校验。跨模块约定见 [ctx_runner 契约迁移](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-29.md)。
+
+## Domain contract migration (2026-10-30)
+
+Introduce immutable `Source` values with validated digest/byte pairs, timestamps and domain context. Retain acquired digests on clock failure. Share single-command receipt validation between reads and writes; borrowed configuration writes never reconnect. See the [schema 4 migration and module contracts](https://github.com/gatework/ctx_runner/blob/main/docs/contracts-2026-10-30.md). Regenerate old collection reports and change plans; changing only their version number is not supported.

data/lib/ctx_driver/capture.rb

@@ -2,6 +2,7 @@
 
 require "ctx_parser/immutable"
 require_relative "command"
+require_relative "source"
 
 module CtxDriver
   # 原始正文须显式读取；默认检查与序列化仅展示采集元数据。
@@ -15,7 +16,7 @@ module CtxDriver
       unless started_at.is_a?(Time) && completed_at.is_a?(Time)
         raise ArgumentError, "Capture timestamps must be Time values"
       end
-      unless evidence.is_a?(Array) && evidence.all? { |entry| entry.is_a?(Hash) }
+      unless evidence.is_a?(Array) && evidence.all? { |entry| (entry.is_a?(Hash) || entry.is_a?(Source)) }
         raise ArgumentError, "Capture evidence must be hashes"
       end
       raise ArgumentError, "Capture failure must be a hash or nil" unless failure.nil? || failure.is_a?(Hash)
@@ -28,7 +29,8 @@ module CtxDriver
       @body = body.nil? || body.frozen? ? body : body.dup.freeze
       @started_at = started_at.frozen? ? started_at : started_at.dup.freeze
       @completed_at = completed_at.frozen? ? completed_at : completed_at.dup.freeze
-      @evidence, @failure = [ evidence, failure ].map { |value| CtxParser::Immutable.copy(value) }
+      @evidence = evidence.map { |entry| Source.coerce(entry) }.freeze
+      @failure = CtxParser::Immutable.copy(failure)
       @skipped = skipped
       freeze
     end
@@ -41,7 +43,7 @@ module CtxDriver
     # 返回公开的数据结构，并保留状态与诊断信息。
     def to_h
       { command: command, started_at: started_at, completed_at: completed_at,
-        evidence: evidence, failure: failure, skipped: skipped? }
+        evidence: evidence.map(&:to_h), failure: failure, skipped: skipped? }
     end
 
     # 序列化诊断元数据，不包含原始来源文本。

data/lib/ctx_driver/reader.rb

@@ -5,6 +5,7 @@ require "time"
 require_relative "capture"
 require_relative "failure"
 require_relative "session"
+require_relative "receipt"
 
 module CtxDriver
   # 借用已打开会话逐条独立查询；连接归属与领域判断由外部负责。
@@ -66,14 +67,7 @@ module CtxDriver
         raise TypeError, "Command output must be text" unless output.is_a?(String)
 
         evidence = [ { command: command, sha256: Digest::SHA256.hexdigest(output), bytes: output.bytesize } ]
-        success = receipt.success?
-        steps = receipt.steps
-        unless [ true, false ].include?(success) && steps.is_a?(Array) && (success ? steps.one? : steps.size <= 1)
-          raise TypeError, "One query must return one completed command"
-        end
-        unless steps.all? { |step| step.is_a?(Hash) && step[:command].is_a?(String) && step[:command].b == command.b }
-          raise TypeError, "Completed step must belong to the requested command"
-        end
+        success = Receipt.validate(receipt, command: command)
         receipt_validated = true
         if success
           body = receipt.value!
@@ -96,7 +90,6 @@ module CtxDriver
           evidence = [ evidence.first.merge(observed_at: observed_at) ]
         end
       rescue StandardError => error
-        evidence = []
         command_failure ||= Failure.details(error, fallback: :invalid_command_result, stage: :response)
       end
       state_failure = detect_session_failure

data/lib/ctx_driver/receipt.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CtxDriver
+  # 读取与配置写入共用单命令回执身份，成功恰好对应一个完成步骤。
+  module Receipt
+    def self.validate(receipt, command:)
+      success, steps = receipt.success?, receipt.steps
+      unless [ true, false ].include?(success) && steps.is_a?(Array) && (success ? steps.one? : steps.size <= 1)
+        raise TypeError, "One query must return one completed command"
+      end
+      unless steps.all? { |step| step.is_a?(Hash) && step[:command].is_a?(String) && step[:command].b == command.b }
+        raise TypeError, "Completed step must belong to the requested command"
+      end
+      success
+    end
+  end
+end

data/lib/ctx_driver/session.rb

@@ -47,6 +47,13 @@ module CtxDriver
     # 复用连接器的真实状态，避免失败后隐式重连。
     def connected? = @session.connected?
 
+    # 配置写入使用连接器的模式提示符；借用已连接会话，不能触发隐式重连。
+    def write_command(command)
+      raise IOError, "Session is closed" unless connected?
+      command = Command.snapshot(command)
+      Response.new(@session.execute_command(command, output_sensitive: true))
+    end
+
     # 单命令操作保护响应正文，并绑定当前完整提示符。
     def send_commands(commands)
       raise ArgumentError, "Expected one query" unless commands.is_a?(Array) && commands.one?

data/lib/ctx_driver/source.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "ctx_parser/immutable"
+require "ctx_parser/values"
+require_relative "command"
+
+module CtxDriver
+  # 来源身份与摘要是值；领域附加信息放入 context，不混入驱动字段。
+  class Source < Data.define(:command, :sha256, :bytes, :reference, :observed_at, :status, :context)
+    def self.coerce(value)
+      return value if value.is_a?(self)
+      raise ArgumentError, "Source must be a mapping" unless value.is_a?(Hash)
+      attributes = value.each_with_object({}) do |(key, entry), result|
+        unless (key.is_a?(String) || key.is_a?(Symbol)) && members.include?(key.to_sym) && !result.key?(key.to_sym)
+          raise ArgumentError, "Source contains unknown or duplicate fields"
+        end
+        result[key.to_sym] = entry
+      end
+      raise ArgumentError, "Invalid source status" if attributes.key?(:status) && attributes[:status].nil?
+      attributes[:status] = attributes[:status].to_sym if value.key?("status") && attributes[:status].is_a?(String)
+      new(**attributes)
+    end
+
+    def initialize(command: nil, sha256: nil, bytes: nil, reference: nil, observed_at: nil, status: nil, context: {})
+      command = Command.snapshot(command) unless command.nil?
+      unless sha256.nil? && bytes.nil? || sha256.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(sha256) && bytes.is_a?(Integer) && bytes >= 0
+        raise ArgumentError, "Source requires a digest and nonnegative byte count together"
+      end
+      unless reference.nil? || reference.is_a?(String) && !reference.strip.empty? && !/[\x00-\x1f\x7f]/.match?(reference)
+        raise ArgumentError, "Invalid source reference"
+      end
+      raise ArgumentError, "Source requires an identity or digest" unless command || reference || sha256
+      unless status.nil? || %i[complete partial failed unsupported].include?(status)
+        raise ArgumentError, "Invalid source status"
+      end
+      raise ArgumentError, "Source context must be a mapping" unless context.is_a?(Hash)
+      observed_at = CtxParser::Values.timestamp(observed_at) if observed_at.is_a?(String)
+      raise ArgumentError, "Source time must be a Time or nil" unless observed_at.nil? || observed_at.is_a?(Time)
+      attributes = { command: command, sha256: sha256&.dup&.freeze, bytes: bytes, reference: reference&.dup&.freeze,
+        observed_at: observed_at&.getutc&.freeze, status: status, context: CtxParser::Immutable.copy(context) }
+      metadata = attributes.compact
+      metadata.delete(:context) if context.empty?
+      metadata[:observed_at] = attributes[:observed_at].iso8601(6).freeze if observed_at
+      @metadata = metadata.freeze
+      super(**attributes)
+    end
+
+    def verified? = !sha256.nil? && !bytes.nil?
+    def to_h = @metadata.dup
+
+    # 元数据映射访问沿用同一字段协议；所有更新重新经过构造校验。
+    def [](key) = @metadata[key]
+    def fetch(...) = @metadata.fetch(...)
+    def key?(key) = @metadata.key?(key)
+    def keys = @metadata.keys
+    def merge(**attributes) = with(**attributes)
+    def inspect = "#<#{self.class.name} verified=#{verified?}>"
+    alias to_s inspect
+    def pretty_print(printer) = printer.text(inspect)
+  end
+end

data/lib/ctx_driver/version.rb

@@ -2,5 +2,5 @@
 
 module CtxDriver
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_driver
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -76,7 +76,9 @@ files:
 - lib/ctx_driver/command.rb
 - lib/ctx_driver/failure.rb
 - lib/ctx_driver/reader.rb
+- lib/ctx_driver/receipt.rb
 - lib/ctx_driver/session.rb
+- lib/ctx_driver/source.rb
 - lib/ctx_driver/version.rb
 homepage: https://github.com/gatework/ctx_driver
 licenses: