kairos-chain 3.43.0 → 3.45.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ef5b418a3202426bfd13d7f62a849363f52144978f6b091c9ebb8bb43564927
-  data.tar.gz: 471e635837cc5e5b65cd704dd78a9b48bd7312f61f7a27aa420c5323c5c0d43b
+  metadata.gz: ea7401710d6467287e35146c84d731c08733f184fac36be13e76de11d7af5433
+  data.tar.gz: a823ba8bf1bb1157394ff04466cdcf96c0347eee50796816fe8c2fd1d188792c
 SHA512:
-  metadata.gz: e45299ac0b7b574419742d6b8243fbd9b492641c37e5f5f1e81e22ea77623e2cf986ca96da63dfdde8cc5f08bef07ff83bb42ab816296c4fe50a002d80805ae5
-  data.tar.gz: 8138a96211b233b85f9e6342a32f2a02745dbf230ad319c274880c659c444ad03bf1909013864a79abeab2dccba7d754edbd3350506e7ffd751b112aac2803b0
+  metadata.gz: a11ba74c10eb1c56ef15b57992755083b6d36bd4fef1ea73bf1cae64afc1f07ad26f8774ee703c3c98eefa25c8a422441c5c5af032b9ae523d7518c7dc50193d
+  data.tar.gz: 26f95dd3245e9e39311349ef540954d200985a59bf9da38b3b08256d11ec50a445d60cc3f0c41538b6a0c0bfb2eb591ce742dc4523950d9ffe8f06471d22e50a

data/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [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.45.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

data/templates/skillsets/synoptis/lib/synoptis/anchoring/anchoring_rule.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'time'
+require_relative 'entry'
+
+module Synoptis
+  module Anchoring
+    # Declared anchoring rule (aud_l2_mutual_anchoring_design v0.5 MAP-3)
+    # under map-1 §5: a result-free rule artifact whose schema is closed by
+    # construction (no field can reference an outcome), committed on the chain
+    # for decidable anteriority, and a coverage CHECKER that reports — never
+    # enforces. A sparse or vacuous rule conforms; the report makes its cost
+    # visible. No automation lives here (cadence automation is out of this
+    # slice; the canonical-works human gate is untouched).
+    module AnchoringRule
+      FORMAT = 'map-1/anchoring-rule'
+      COMMITMENT_FORMAT = 'map-1/rule-commitment'
+      TRIGGERS = %w[every_n_records every_n_days].freeze
+      FIELDS = %w[format n trigger].freeze
+      HEX_DIGEST = /\A[a-f0-9]{64}\z/
+      # JSON-safe bound, matching HeadBinding (ANC-2 boundedness).
+      JSON_SAFE_BOUND = 2**53
+
+      class RuleError < StandardError; end
+
+      module_function
+
+      # Build a rule artifact string (canonical JSON, map-1 §5).
+      def build(trigger, n)
+        t = trigger.to_s
+        raise RuleError, "trigger must be one of #{TRIGGERS.join(', ')}, got #{t.inspect}" unless TRIGGERS.include?(t)
+        unless n.is_a?(Integer) && n.positive? && n < JSON_SAFE_BOUND
+          raise RuleError, "n must be a positive JSON-safe Integer, got #{n.inspect}"
+        end
+
+        Entry.canonical_json('format' => FORMAT, 'n' => n, 'trigger' => t)
+      end
+
+      # Parse + validate a rule artifact string. Raises RuleError on the first
+      # violation (a rule is an operator-authored artifact: malformed means
+      # refused, not coerced).
+      def parse!(rule_string)
+        parsed = begin
+          JSON.parse(rule_string.to_s)
+        rescue JSON::ParserError => e
+          raise RuleError, "rule is not valid JSON: #{e.message}"
+        end
+        raise RuleError, "rule must be a JSON object, got #{parsed.class}" unless parsed.is_a?(Hash)
+
+        r = parsed.transform_keys(&:to_s)
+        keys = r.keys.sort
+        raise RuleError, "rule fields must be exactly #{FIELDS.join(', ')}, got #{keys.join(', ')}" unless keys == FIELDS
+        raise RuleError, "unknown format #{r['format'].inspect} (#{FORMAT} only)" unless r['format'] == FORMAT
+        raise RuleError, "trigger must be one of #{TRIGGERS.join(', ')}" unless TRIGGERS.include?(r['trigger'])
+        unless r['n'].is_a?(Integer) && r['n'].positive? && r['n'] < JSON_SAFE_BOUND
+          raise RuleError, 'rule.n must be a positive JSON-safe Integer'
+        end
+        # map-1 §5: a rule is valid only in its canonical serialization, so one
+        # rule has exactly one digest — a re-ordered or re-spaced serialization
+        # would commit a different digest for the same logical rule.
+        unless Entry.canonical_json(r) == rule_string.to_s
+          raise RuleError, 'rule is not in canonical serialization (map-1 §5: one rule, one digest)'
+        end
+
+        r
+      end
+
+      # The rule-commitment record string (map-1 §5) the chain commits so the
+      # rule's anteriority is decidable in committed order (MPR-8).
+      def commitment_record(rule_string)
+        parse!(rule_string)
+        Entry.canonical_json(
+          'format' => COMMITMENT_FORMAT,
+          'rule_digest' => Digest::SHA256.hexdigest(rule_string.to_s)
+        )
+      end
+
+      # Coverage report (map-1 §5): the rule held against the visible anchor
+      # history. Diagnostic posture: never raises on the history side — asked
+      # "is this history covered?", the answer is a report, not an exception.
+      #
+      # +rule_string+   the committed rule artifact.
+      # +anchors+       the binding-carrying anchor observations, each a Hash
+      #                 with 'tree_size' (Integer) and 'moment' (ISO8601
+      #                 String) — the shape a reader extracts from head
+      #                 bindings + entry moments.
+      # +chain_extent+  current record count of the internal chain.
+      # +rule_position+ committed record position of the rule commitment
+      #                 (for every_n_records) — expectation starts after it.
+      # +rule_moment+   committed moment of the rule commitment (ISO8601, for
+      #                 every_n_days).
+      # +now+           end of the assessed window (ISO8601); required for
+      #                 every_n_days so the checker stays clock-free.
+      #
+      # Returns { conforms: true, expected: [...], matched: [...], gaps: [...],
+      #           note: } — `conforms` is always true for a valid rule (MAP-3:
+      #           a vacuous rule conforms); the gaps are the visible cost.
+      def coverage(rule_string, anchors, chain_extent: nil, rule_position: nil, rule_moment: nil, now: nil)
+        rule = parse!(rule_string)
+        observations = Array(anchors).map { |a| a.is_a?(Hash) ? a.transform_keys(&:to_s) : {} }
+
+        case rule['trigger']
+        when 'every_n_records'
+          coverage_by_records(rule, observations, chain_extent, rule_position)
+        when 'every_n_days'
+          coverage_by_days(rule, observations, rule_moment, now)
+        end
+      end
+
+      # -- internal helpers --
+
+      def coverage_by_records(rule, observations, chain_extent, rule_position)
+        extent = begin
+          Integer(chain_extent || 0)
+        rescue ArgumentError, ::TypeError
+          raise RuleError, "chain_extent must be an Integer, got #{chain_extent.inspect}"
+        end
+        start = begin
+          Integer(rule_position || 0)
+        rescue ArgumentError, ::TypeError
+          raise RuleError, "rule_position must be an Integer, got #{rule_position.inspect}"
+        end
+        n = rule['n']
+        sizes = observations.map { |o| o['tree_size'] }.select { |s| s.is_a?(Integer) }.sort
+        expected = []
+        threshold = start + n
+        while threshold <= extent
+          expected << threshold
+          threshold += n
+        end
+        matched = expected.select { |e| sizes.any? { |s| s >= e && s < e + n } }
+        gaps = expected - matched
+        {
+          conforms: true,
+          # Echo the assessed frame so a defaulted rule_position is visible in
+          # the report, never silently assumed.
+          chain_extent: extent,
+          rule_position: start,
+          expected: expected,
+          matched: matched,
+          gaps: gaps,
+          note: gaps.empty? ? 'covered' : "#{gaps.size} expected anchor point(s) without a binding-carrying anchor; temporal windows widen accordingly (MPR-7)"
+        }
+      end
+
+      def coverage_by_days(rule, observations, rule_moment, now)
+        raise RuleError, 'every_n_days coverage needs rule_moment and now (ISO8601)' if rule_moment.nil? || now.nil?
+
+        t0 = Time.iso8601(rule_moment.to_s)
+        t1 = Time.iso8601(now.to_s)
+        n_sec = rule['n'] * 86_400
+        moments = observations.map { |o| o['moment'] }.filter_map do |m|
+          Time.iso8601(m.to_s)
+        rescue ArgumentError
+          nil
+        end
+        expected = []
+        boundary = t0 + n_sec
+        while boundary <= t1
+          expected << boundary.utc.iso8601
+          boundary += n_sec
+        end
+        matched = expected.select do |e|
+          et = Time.iso8601(e)
+          moments.any? { |m| m >= et && m < et + n_sec }
+        end
+        gaps = expected - matched
+        {
+          conforms: true,
+          rule_moment: t0.utc.iso8601,
+          assessed_until: t1.utc.iso8601,
+          expected: expected,
+          matched: matched,
+          gaps: gaps,
+          note: gaps.empty? ? 'covered' : "#{gaps.size} expected anchor window(s) without a binding-carrying anchor; temporal windows widen accordingly (MPR-7)"
+        }
+      rescue ArgumentError => e
+        raise RuleError, "invalid ISO8601 input: #{e.message}"
+      end
+    end
+  end
+end