kairos-chain 3.43.0 → 3.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ef5b418a3202426bfd13d7f62a849363f52144978f6b091c9ebb8bb43564927
-  data.tar.gz: 471e635837cc5e5b65cd704dd78a9b48bd7312f61f7a27aa420c5323c5c0d43b
+  metadata.gz: 372dd921a298d45c97b957ae724a253bb22da73b5bb211025fe894eab5de4ff7
+  data.tar.gz: f15e37a2caeef2d4d08b92f49608aa52307b1a93124a1742d3f40c10ae145bf8
 SHA512:
-  metadata.gz: e45299ac0b7b574419742d6b8243fbd9b492641c37e5f5f1e81e22ea77623e2cf986ca96da63dfdde8cc5f08bef07ff83bb42ab816296c4fe50a002d80805ae5
-  data.tar.gz: 8138a96211b233b85f9e6342a32f2a02745dbf230ad319c274880c659c444ad03bf1909013864a79abeab2dccba7d754edbd3350506e7ffd751b112aac2803b0
+  metadata.gz: c9fc60d9acee8dcb8b7a2bfb43021d3c8b129cb94471fe8488092683ade4755665faa72860fb8c1bed77d254e977226c3d8cd85bec4dfe95eea2d0dc12352190
+  data.tar.gz: e5769c4b23ce1daef9704423f41e097d8969f5b86442ab1592beab4e3dc7623a3a79e30aba51d7ca2d5621e55fd635db740b5489761995bc2b9b33de8eb0b80e

data/CHANGELOG.md

@@ -4,6 +4,72 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.46.0] - 2026-07-22
+
+### Synoptis — reproduction endorsement rpr-1 (AUD-L3 slice 1)
+
+Implements AUD-L3 design v0.4 (RPR-1..5, review-converged) slice 1 in the
+synoptis SkillSet. All additive: rpr-1 builds on map-1/khab-1 exactly as
+map-1 built on khab-1; no pre-existing file changed.
+
+- `conventions/rpr-1.md`: content-addressed reproduction-endorsement
+  convention — re-execution target (inputs/environment/pipeline/output
+  digests; the first three form the committed computation identification,
+  output excluded), target-bound result-free tolerance declaration
+  (bit-identity at rpr-1), reproduction endorsement carrying the adjudicated
+  verdict (reproduced / not-reproduced) and its adjudication mode
+  (hand / procedure), declaration-set assessment (order-independent, sibling
+  targets pooled by computation identification, residue disclosed), map-1 §3
+  retraction reused unchanged.
+- `reproduction.rb`: build/parse/digest for target, tolerance, endorsement
+  (closed schemas, canonical-serialization equality, refuse-not-coerce);
+  endorsement signing/verification via the unchanged map-1 §1.1 attestation
+  signature (ChainCredential); foreignness conformance check (RPR-4);
+  declaration-set assessment reporting invoked commitment (earliest
+  anterior), posterior commitments, digest-tiebroken rank, distinct-digest
+  multiplicity, and unresolved-equivalence residue.
+- `bin/rpr_verify.rb`: offline auditor verifier (target / tolerance /
+  endorsement / assess / convention). Strict intake (at most one trailing
+  LF via delete_suffix — CRLF refused), canonical base-10 numerals only,
+  exit-code discipline (0 verified/report, 1 rejected, 2 unresolvable),
+  RPR-1/RPR-4 condition disclosure in output.
+- `test/test_rpr_reproduction.rb`: 37 design-constraint assertions
+  (RPR-1..5), including presentation-order independence of the assessment
+  and rank, CRLF/padding refusal, and map-1 non-interference (75/75
+  regression green).
+
+Implementation review: 3 rounds, R3 5/5 APPROVE, zero remaining P0/P1
+(executable-probe personas; dispositions in docs/drafts/).
+
+## [3.45.0] - 2026-07-21
+
+### Synoptis — mutual anchoring protocol MAP-1..4 (map-1, AUD-L2)
+
+Implements AUD-L2 design v0.5 (FROZEN) slice 1 in the synoptis SkillSet:
+
+- `conventions/map-1.md`: content-addressed mutual-anchoring convention
+  (chain identity credential, typed attestation vocabulary, succession
+  records, declared anchoring rule, changeover event). Builds on khab-1
+  without modifying it.
+- `chain_credential.rb`: Ed25519 self-authenticating chain identity
+  credential — verification needs no registry and no network.
+- `succession.rb`: succession governance (earliest non-retracted designation
+  governs; at-or-before changeover boundary; issuer-only retraction;
+  retract-and-redesignate trails surfaced in the contested register).
+- `anchoring_rule.rb`: result-free declared anchoring rule (closed schema)
+  with a coverage checker that reports and never enforces.
+- `attestation_types.rb`: MAP-4 vocabulary intake validation and anchor-log
+  retraction coherence (issuer = depositor at map-1, disclosed deferral).
+- `entry.rb` / `log.rb` / `write_path.rb`: additive `attestation_type` on
+  newly appended entries only (AHM-4 byte-invariance preserved).
+- `bin/map_verify.rb`: standalone offline verifier (credential, attestation,
+  succession, coverage, pair, retraction subcommands).
+- `test/test_map_anchoring.rb`: 75 design-constraint tests.
+
+Design review converged R5 5/6 APPROVE; implementation review converged
+R4 5/5 APPROVE with zero residual P0/P1. The inaugural mutual anchor with a
+second, independently operated HestiaChain instance is deliberately pending.
+
 ## [3.42.2] - 2026-07-14
 
 ### Knowledge — loop_engineering_patterns §B: Model/Effort budget allocation

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.43.0"
+  VERSION = "3.46.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/synoptis/bin/khab_verify.rb

@@ -0,0 +1,172 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# khab_verify — offline auditor verifier for khab-1 head bindings (MPR-4).
+#
+# Verifies inclusion and consistency proofs with EXACTLY the disclosed trust
+# base: the proof artifact, the published head binding(s), and the shipped
+# khab-1 convention definition. No internal-chain access, no operator
+# cooperation, no network. (The authentic anchor-log view — that the binding
+# really is committed at its claimed position — is checked against the log's
+# public verification surface, outside this script.)
+#
+# Usage:
+#   khab_verify.rb inclusion   <proof.json> <binding.json>
+#   khab_verify.rb consistency <proof.json> <earlier_binding.json> <later_binding.json>
+#
+# A binding file may be the bare head_binding object, or any JSON object
+# carrying it under "head_binding" (e.g. a public-verifier record or an anchor
+# entry body).
+#
+# Exit status: 0 = VERIFIED, 1 = REJECTED, 2 = usage / unresolvable input.
+
+require 'json'
+require 'digest'
+require_relative '../lib/synoptis/anchoring/cumulative_commitment'
+
+CONVENTION_PATH = File.expand_path('../lib/synoptis/anchoring/conventions/khab-1.md', __dir__)
+CC = Synoptis::Anchoring::CumulativeCommitment
+
+def die(msg)
+  warn "khab_verify: #{msg}"
+  exit 2
+end
+
+def reject(msg)
+  puts "REJECTED: #{msg}"
+  exit 1
+end
+
+def load_json(path)
+  parsed = JSON.parse(File.read(path))
+  die "#{path}: expected a JSON object, got #{parsed.class}" unless parsed.is_a?(Hash)
+  parsed
+rescue JSON::ParserError, SystemCallError => e
+  die "cannot read #{path}: #{e.message}"
+end
+
+def extract_binding(obj, path)
+  b = obj.is_a?(Hash) && obj.key?('head_binding') ? obj['head_binding'] : obj
+  die "#{path} carries no head binding" unless b.is_a?(Hash) && b['convention']
+  b
+end
+
+# Structural well-formedness of a binding's verifiable fields, checked BEFORE
+# any verdict logic. The strongest claims this verifier can emit (VERIFIED,
+# DIVERGENCE) must be unreachable from malformed input: a missing or
+# non-canonical root/extent is unresolvable input (exit 2), never evidence.
+def require_wellformed!(binding, path)
+  unless binding['cumulative_root'].is_a?(String) && binding['cumulative_root'].match?(/\A[a-f0-9]{64}\z/)
+    die "#{path}: cumulative_root missing or not 64-char lowercase hex (khab-1 §4)"
+  end
+  unless binding['tree_size'].is_a?(Integer) && binding['tree_size'].positive? && binding['tree_size'] < 2**53
+    die "#{path}: tree_size missing or not a positive JSON-safe integer (khab-1 §4)"
+  end
+  return if binding['chain_identity'].is_a?(String) &&
+            binding['chain_identity'].match?(/\Ablock1-sha256:[a-f0-9]{64}\z/)
+
+  die "#{path}: chain_identity missing or not in khab-1 §5 canonical form (block1-sha256:<64-hex>)"
+end
+
+# MPR-3: the convention identifier must resolve to a definition whose own
+# integrity the auditor can verify. A digest mismatch means the binding was
+# computed under a definition this verifier does not hold — unresolvable, so
+# verification refuses rather than guessing.
+def check_convention!(binding)
+  reject "unknown convention #{binding['convention'].inspect} (this verifier implements khab-1)" unless
+    binding['convention'] == 'khab-1'
+  local = begin
+    Digest::SHA256.hexdigest(File.binread(CONVENTION_PATH))
+  rescue SystemCallError => e
+    die "khab-1 convention definition unreadable at #{CONVENTION_PATH}: #{e.message}"
+  end
+  return if binding['convention_sha256'] == local
+
+  reject "convention_sha256 #{binding['convention_sha256']} does not match the held khab-1 " \
+         "definition (#{local}); convention unresolvable"
+end
+
+def require_match(proof, binding, proof_key, binding_key, label)
+  return if proof[proof_key] == binding[binding_key]
+
+  reject "proof #{label} #{proof[proof_key].inspect} does not match binding #{binding[binding_key].inspect}"
+end
+
+mode = ARGV.shift
+
+case mode
+when 'inclusion'
+  die 'usage: khab_verify.rb inclusion <proof.json> <binding.json>' unless ARGV.size == 2
+  proof = load_json(ARGV[0])
+  binding = extract_binding(load_json(ARGV[1]), ARGV[1])
+  check_convention!(binding)
+  require_wellformed!(binding, ARGV[1])
+  reject "proof format #{proof['format'].inspect} is not khab-1/inclusion" unless proof['format'] == 'khab-1/inclusion'
+  require_match(proof, binding, 'chain_identity', 'chain_identity', 'chain_identity')
+  require_match(proof, binding, 'tree_size', 'tree_size', 'tree_size')
+  require_match(proof, binding, 'cumulative_root', 'cumulative_root', 'cumulative_root')
+
+  ok = CC.verify_inclusion(
+    record_commitment: proof['record_commitment'],
+    index: proof['index'],
+    tree_size: binding['tree_size'],
+    path: proof['path'],
+    root: binding['cumulative_root']
+  )
+  reject 'inclusion proof does not recompute the committed cumulative root' unless ok
+
+  puts 'VERIFIED: record commitment ' \
+       "#{proof['record_commitment']} is member ##{proof['index']} of the anchored state " \
+       "(tree_size #{binding['tree_size']}, chain #{binding['chain_identity']})."
+  puts 'Scope (MPR-5/6): membership, integrity at anchor time, position, order — nothing about ' \
+       'content quality or completeness of anchoring; commitment, not content.'
+
+when 'consistency'
+  die 'usage: khab_verify.rb consistency <proof.json> <earlier.json> <later.json>' unless ARGV.size == 3
+  proof = load_json(ARGV[0])
+  earlier = extract_binding(load_json(ARGV[1]), ARGV[1])
+  later = extract_binding(load_json(ARGV[2]), ARGV[2])
+  check_convention!(earlier)
+  check_convention!(later)
+  require_wellformed!(earlier, ARGV[1])
+  require_wellformed!(later, ARGV[2])
+  reject "proof format #{proof['format'].inspect} is not khab-1/consistency" unless proof['format'] == 'khab-1/consistency'
+  # MPR-9: extension-relatedness is defined only over the same committed chain
+  # identity; different identities terminate the claim rather than failing it.
+  reject "bindings commit different chain identities (#{earlier['chain_identity']} vs " \
+         "#{later['chain_identity']}); extension claim terminated across an identity change" unless
+    earlier['chain_identity'] == later['chain_identity']
+  # Equal committed extent with different committed roots needs no proof at
+  # all: the two states differ at the same size, so no extension relation can
+  # exist. This is arithmetic on the committed bindings — a POSITIVE
+  # divergence witness (MPR-9), unlike a mere proof-verification failure.
+  if earlier['tree_size'] == later['tree_size'] && earlier['cumulative_root'] != later['cumulative_root']
+    puts "DIVERGENCE: both bindings commit chain #{later['chain_identity']} at extent " \
+         "#{later['tree_size']} with different cumulative roots; conclusive evidence of " \
+         'rewriting or forking (MPR-9)'
+    exit 1
+  end
+  require_match(proof, earlier, 'first_root', 'cumulative_root', 'first_root')
+  require_match(proof, later, 'second_root', 'cumulative_root', 'second_root')
+  require_match(proof, earlier, 'first_size', 'tree_size', 'first_size')
+  require_match(proof, later, 'second_size', 'tree_size', 'second_size')
+
+  ok = CC.verify_consistency(
+    first_root: earlier['cumulative_root'],
+    first_size: earlier['tree_size'],
+    second_root: later['cumulative_root'],
+    second_size: later['tree_size'],
+    path: proof['path']
+  )
+  # Design §11: failure of an operator-supplied proof is NOT by itself a
+  # positive inconsistency witness — report it as unestablished, not as forgery.
+  reject 'consistency proof does not verify; extension claim remains UNESTABLISHED ' \
+         '(not by itself evidence of rewriting — MPR-9)' unless ok
+
+  puts "VERIFIED: the later anchored state (tree_size #{later['tree_size']}) commits to an " \
+       "extension of the earlier state (tree_size #{earlier['tree_size']}) unchanged as a prefix " \
+       "(chain #{later['chain_identity']})."
+
+else
+  die "usage: khab_verify.rb {inclusion|consistency} <proof.json> <binding(s).json...>"
+end

data/templates/skillsets/synoptis/bin/map_verify.rb

@@ -0,0 +1,250 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# map_verify — offline auditor verifier for map-1 mutual-anchoring artifacts
+# (MAP-1..4, aud_l2_mutual_anchoring_design v0.5).
+#
+# Verifies with EXACTLY the disclosed trust base: the artifacts named on the
+# command line plus the shipped map-1 convention definition. No registry, no
+# network, no operator cooperation. (Authentic log/chain views are the
+# caller's inputs; their own integrity is checked by the khab-1 surface.)
+#
+# Usage:
+#   map_verify.rb credential  <credential.json>
+#   map_verify.rb attestation <credential.json> <payload-file> <signature-hex>
+#   map_verify.rb succession  <old_credential.json> <records.json> [changeover_position]
+#       records.json = JSON array of internal-chain record STRINGS, committed order
+#   map_verify.rb coverage    <rule-file> <anchors.json> [chain_extent] [rule_position] [rule_moment] [now]
+#       anchors.json = JSON array of {"tree_size":..,"moment":".."} observations;
+#       every_n_records needs chain_extent (+ optional rule_position);
+#       every_n_days needs rule_moment and now (ISO8601) as args 5 and 6 —
+#       pass 0 0 for the unused args 3 and 4.
+#   map_verify.rb pair        <log_a.json> <identity_a> <log_b.json> <identity_b>
+#       log_*.json = JSON array of anchor-entry objects (entry.to_h shape);
+#       reports what a verified pair establishes (MAP-1) — and ONLY that.
+#   map_verify.rb retraction  <log.json> <retraction_entry_hash>
+#       checks map-1 §3 coherence of an anchor-log retraction against its target.
+#
+# Exit status: 0 = VERIFIED/REPORT, 1 = REJECTED, 2 = usage / unresolvable.
+
+require 'json'
+require 'digest'
+require_relative '../lib/synoptis/anchoring/entry'
+require_relative '../lib/synoptis/anchoring/chain_credential'
+require_relative '../lib/synoptis/anchoring/succession'
+require_relative '../lib/synoptis/anchoring/anchoring_rule'
+require_relative '../lib/synoptis/anchoring/attestation_types'
+
+ENTRY = Synoptis::Anchoring::Entry
+CRED = Synoptis::Anchoring::ChainCredential
+SUCC = Synoptis::Anchoring::Succession
+RULE = Synoptis::Anchoring::AnchoringRule
+ATYPE = Synoptis::Anchoring::AttestationTypes
+
+def die(msg)
+  warn "map_verify: #{msg}"
+  exit 2
+end
+
+def reject(msg)
+  puts "REJECTED: #{msg}"
+  exit 1
+end
+
+def load_json(path)
+  JSON.parse(File.read(path))
+rescue JSON::ParserError, SystemCallError => e
+  die "cannot read #{path}: #{e.message}"
+end
+
+# Malformed caller input is unresolvable (exit 2), never a verdict.
+# Explicit base 10: Integer('010') would read octal and silently shift a
+# governance boundary.
+def strict_int(value, label)
+  # Digits only: Integer() would also accept '1_0' and padded whitespace.
+  die "#{label} must be a base-10 integer, got #{value.inspect}" unless value.is_a?(String) && value.match?(/\A\d+\z/)
+  Integer(value, 10)
+end
+
+def load_json_hash(path, label)
+  parsed = load_json(path)
+  die "#{path}: #{label} must be a JSON object, got #{parsed.class}" unless parsed.is_a?(Hash)
+  parsed
+end
+
+HEX64 = /\A[a-f0-9]{64}\z/
+
+# Structural well-formedness of a matched head binding (khab-1 §4 shapes).
+# The strongest claim this tool prints must be unreachable from malformed
+# input: a garbage binding is unresolvable, never PAIR ESTABLISHED.
+def require_binding_wellformed!(binding, where)
+  die "#{where}: head_binding.convention is #{binding['convention'].inspect}, not khab-1" unless binding['convention'] == 'khab-1'
+  %w[convention_sha256 cumulative_root].each do |k|
+    die "#{where}: head_binding.#{k} missing or not 64-char lowercase hex" unless binding[k].is_a?(String) && binding[k].match?(HEX64)
+  end
+  die "#{where}: head_binding.tree_size must be a positive Integer" unless binding['tree_size'].is_a?(Integer) && binding['tree_size'].positive?
+  unless binding['chain_identity'].is_a?(String) && binding['chain_identity'].match?(/\Ablock1-sha256:[a-f0-9]{64}\z/)
+    die "#{where}: head_binding.chain_identity is not block1-sha256:<64-hex> (khab-1 §5)"
+  end
+end
+
+# Recompute an entry's committed hash from its canonical content. Detects an
+# in-place edited entry without any chain access; the full log hash chain is
+# the khab-1 surface's business (khab_verify / public verifier).
+def require_entry_hash!(entry_h, where)
+  content = { 'position' => entry_h['position'], 'prev' => entry_h['prev'],
+              'kind' => entry_h['kind'], 'body' => entry_h['body'] }
+  recomputed = ENTRY.compute_hash(content)
+  return if recomputed == entry_h['entry_hash']
+
+  reject "#{where}: entry_hash does not recompute from committed content (edited in place?)"
+end
+
+mode = ARGV.shift
+
+case mode
+when 'credential'
+  die 'usage: map_verify.rb credential <credential.json>' unless ARGV.size == 1
+  cred = load_json_hash(ARGV[0], 'credential')
+  begin
+    CRED.validate!(cred)
+  rescue CRED::CredentialError => e
+    reject e.message
+  end
+  puts "VERIFIED: credential digest #{CRED.credential_digest(cred)} binds #{cred['chain_identity']}"
+  puts 'NOTE: binding is a SELF-attestation (map-1 §1); that the credential speaks'
+  puts 'for the chain requires the chain to commit the credential digest (map-1 §2).'
+
+when 'attestation'
+  die 'usage: map_verify.rb attestation <credential.json> <payload-file> <signature-hex>' unless ARGV.size == 3
+  cred = load_json_hash(ARGV[0], 'credential')
+  payload = begin
+    File.binread(ARGV[1])
+  rescue SystemCallError => e
+    die "cannot read #{ARGV[1]}: #{e.message}"
+  end
+  begin
+    ok = CRED.verify_attestation(cred, payload, ARGV[2])
+  rescue CRED::CredentialError => e
+    reject e.message
+  end
+  reject 'attestation signature does not verify under the credential' unless ok
+  puts "VERIFIED: attestation signature valid under credential #{CRED.credential_digest(cred)[0, 12]}…"
+
+when 'succession'
+  die 'usage: map_verify.rb succession <old_credential.json> <records.json> [changeover_position]' unless (2..3).cover?(ARGV.size)
+  cred = load_json_hash(ARGV[0], 'credential')
+  records = load_json(ARGV[1])
+  unless records.is_a?(Array) && records.all? { |r| r.is_a?(String) }
+    die "#{ARGV[1]}: expected a JSON array of record STRINGS (each element the exact committed record string)"
+  end
+  changeover = ARGV[2].nil? ? nil : strict_int(ARGV[2], 'changeover_position')
+  die 'changeover_position must be non-negative' if !changeover.nil? && changeover.negative?
+  begin
+    verdict = SUCC.governance(cred, records, changeover_position: changeover)
+  rescue CRED::CredentialError => e
+    reject e.message
+  end
+  puts JSON.pretty_generate(verdict)
+  puts 'NOTE: the verdict reports what the records show, never intent (key'
+  puts 'compromise is indistinguishable from the issuer — MAP-2 disclosed limit).'
+
+when 'coverage'
+  unless (2..6).cover?(ARGV.size)
+    die 'usage: map_verify.rb coverage <rule-file> <anchors.json> [chain_extent] [rule_position] [rule_moment] [now]'
+  end
+  rule_string = begin
+    File.read(ARGV[0]).strip
+  rescue SystemCallError => e
+    die "cannot read #{ARGV[0]}: #{e.message}"
+  end
+  rule = begin
+    RULE.parse!(rule_string)
+  rescue RULE::RuleError => e
+    reject e.message
+  end
+  anchors = load_json(ARGV[1])
+  die "#{ARGV[1]}: expected a JSON array of observations" unless anchors.is_a?(Array)
+  extent = ARGV[2].nil? ? nil : strict_int(ARGV[2], 'chain_extent')
+  rule_pos = ARGV[3].nil? ? nil : strict_int(ARGV[3], 'rule_position')
+  rule_moment = ARGV[4]
+  now = ARGV[5]
+  # A tool capability gap is a usage error (exit 2), never a REJECTED verdict.
+  if rule['trigger'] == 'every_n_records' && extent.nil?
+    die 'every_n_records coverage needs chain_extent'
+  end
+  if rule['trigger'] == 'every_n_days' && (rule_moment.nil? || now.nil?)
+    die 'every_n_days coverage needs rule_moment and now (ISO8601), as arguments 5 and 6'
+  end
+  begin
+    report = RULE.coverage(rule_string, anchors, chain_extent: extent, rule_position: rule_pos,
+                                                 rule_moment: rule_moment, now: now)
+  rescue RULE::RuleError => e
+    reject e.message
+  end
+  puts JSON.pretty_generate(report)
+
+when 'pair'
+  die 'usage: map_verify.rb pair <log_a.json> <identity_a> <log_b.json> <identity_b>' unless ARGV.size == 4
+  log_a, id_a, log_b, id_b = load_json(ARGV[0]), ARGV[1], load_json(ARGV[2]), ARGV[3]
+  [[log_a, ARGV[0]], [log_b, ARGV[2]]].each do |(log, path)|
+    die "#{path}: expected a JSON array of anchor-entry objects" unless log.is_a?(Array)
+  end
+  find = lambda do |log, identity, where|
+    log.each_with_index.filter_map do |entry, i|
+      e = entry.is_a?(Hash) ? entry.transform_keys(&:to_s) : {}
+      # Only anchor entries carry head bindings; anything else shaped to look
+      # like one never counts toward a pair.
+      next unless e['kind'] == 'anchor'
+
+      body = e['body'].is_a?(Hash) ? e['body'] : {}
+      hb = body['head_binding']
+      next unless hb.is_a?(Hash) && hb['chain_identity'] == identity
+
+      require_binding_wellformed!(hb, "#{where} entry #{e['position'] || i}")
+      require_entry_hash!(e, "#{where} entry #{e['position'] || i}")
+      { position: e['position'] || i, cumulative_root: hb['cumulative_root'],
+        tree_size: hb['tree_size'], attestation_type: body['attestation_type'] }
+    end
+  end
+  a_holds_b = find.call(log_a, id_b, ARGV[0])
+  b_holds_a = find.call(log_b, id_a, ARGV[2])
+  reject "no entry in #{ARGV[0]} commits a head binding of #{id_b}" if a_holds_b.empty?
+  reject "no entry in #{ARGV[2]} commits a head binding of #{id_a}" if b_holds_a.empty?
+  puts 'PAIR ESTABLISHED (MAP-1 — exactly this, nothing stronger):'
+  puts "  #{id_b} head(s) committed in log A at #{a_holds_b.map { |e| e[:position] }.join(', ')}"
+  puts "  #{id_a} head(s) committed in log B at #{b_holds_a.map { |e| e[:position] }.join(', ')}"
+  untyped = (a_holds_b + b_holds_a).count { |e| e[:attestation_type].nil? }
+  puts "  untyped (pre-map-1, grandfathered) inscriptions: #{untyped}" if untyped.positive?
+  puts 'CONDITIONS (travel with every stronger reading, map-1 §6):'
+  puts '  - partner independence is auditor-supplied; a common operator can fabricate the pair'
+  puts '  - temporal weight reaches only as far as each log\'s own khab-1 anchoring'
+  puts '  - equivocation detection requires authentic views of BOTH logs and cross-comparison'
+  puts '  - matched entry hashes recomputed and binding shapes checked here; full log hash-chain'
+  puts '    and cumulative-root verification are the khab-1 surface\'s business (khab_verify)'
+  puts '  - this pair supplies split-view detection material; it closes nothing'
+
+when 'retraction'
+  die 'usage: map_verify.rb retraction <log.json> <retraction_entry_hash>' unless ARGV.size == 2
+  log = load_json(ARGV[0])
+  die "#{ARGV[0]}: expected a JSON array of anchor-entry objects" unless log.is_a?(Array)
+  entries = log.map { |e| e.is_a?(Hash) ? e.transform_keys(&:to_s) : {} }
+  retraction = entries.find { |e| e['entry_hash'] == ARGV[1] }
+  die "no entry with entry_hash #{ARGV[1]} in #{ARGV[0]}" if retraction.nil?
+  body = retraction['body'].is_a?(Hash) ? retraction['body'] : {}
+  meta = body['metadata'].is_a?(Hash) ? body['metadata'] : {}
+  target_ref = meta['target_entry_hash']
+  unless target_ref.is_a?(String) && target_ref.match?(HEX64)
+    reject "retraction carries no resolvable metadata.target_entry_hash (got #{target_ref.inspect})"
+  end
+  target = entries.find { |e| e['entry_hash'] == target_ref }
+  reject "target entry #{target_ref} not present in the supplied log view" if target.nil?
+  require_entry_hash!(retraction, 'retraction')
+  require_entry_hash!(target, 'target')
+  verdict = ATYPE.retraction_coherence(retraction, target)
+  puts JSON.pretty_generate(verdict)
+  exit(verdict[:coherent] ? 0 : 1)
+
+else
+  die 'usage: map_verify.rb credential|attestation|succession|coverage|pair|retraction ... (see header)'
+end