textus 0.55.1 → 0.56.0

data/lib/textus/boot.rb

@@ -1,202 +0,0 @@
-module Textus
-  # Read-only "what's in this store and how do I use it" envelope.
-  # Boot is side-effect-free. Reads from pre-computed artifacts and
-  # the store catalog rather than computing inline.
-  module Boot
-    PROTOCOL_ID = PROTOCOL
-
-    # Human-readable name(s) for the live lane(s) of a given kind, or `fallback`
-    # when the manifest declares none. Lets write-flow guidance name the live
-    # lane by kind instead of a hardcoded instance name (ADR 0034).
-    def self.lane_label(manifest, kind, fallback)
-      lanes = manifest.policy.lanes_of_kind(kind)
-      lanes.empty? ? fallback : lanes.join(", ")
-    end
-
-    # Static, store-independent parts of the agent-facing protocol. The
-    # `recipes` and `role_resolution` blocks are derived per-manifest in
-    # agent_protocol(...) because lane and role names are user-configurable.
-    AGENT_PROTOCOL_TEMPLATE = {
-      "envelope_shape" => {
-        "summary" => "every read/write payload is a JSON envelope with _meta, body, uid, and etag",
-        "fields" => {
-          "_meta" => "hash of structured frontmatter; schema-validated per entry family",
-          "body" => "string payload (markdown/text) or nil for json/yaml formats where body lives in _meta",
-          "uid" => "stable 16-char hex identifier; preserved across writes and key renames",
-          "etag" => "content hash; pass back on writes to detect concurrent edits",
-        },
-        "ref" => "SPEC.md §8",
-      },
-    }.freeze
-
-    # Curated agent-facing verb catalog. This declares which verbs the operator
-    # CLI surfaces and in what order — the editorial presentation. The summary of
-    # each verb is a fact, not presentation: it is derived from `contract.summary`
-    # at load time (ADR 0039). A literal "summary" survives here only for grouped
-    # CLI tokens (schema/key/rule/hook) that aggregate several sub-contracts and so
-    # have no single contract to derive from. CLI_VERBS itself is assigned in
-    # textus.rb after Zeitwerk eager_load so all contract files are present.
-    CURATED_CLI_VERBS = [
-      { "name" => "boot" },
-      { "name" => "list" },
-      { "name" => "get" },
-      { "name" => "ingest" },
-      { "name" => "where" },
-      { "name" => "schema", "summary" => "schema operations: 'schema show KEY', 'schema diff', 'schema init', 'schema migrate'" },
-      { "name" => "put" },
-      { "name" => "propose" },
-      { "name" => "accept" },
-      { "name" => "enqueue" },
-      { "name" => "key", "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
-      { "name" => "drain" },
-      { "name" => "audit" },
-      { "name" => "blame" },
-      { "name" => "rule", "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
-      { "name" => "doctor" },
-      { "name" => "jobs" },
-      { "name" => "pulse" },
-    ].freeze
-
-    # verb token => contract.summary, for every Dispatcher verb that carries a
-    # contract. The single source for a verb's one-line summary (ADR 0039).
-    def self.contract_summaries
-      Textus::Action::VERBS.values
-                           .select { |k| k.respond_to?(:contract?) && k.contract? }
-                           .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
-    end
-
-    # Build the CLI verb catalog: each summary is derived from its contract when
-    # one exists, falling back to the curated editorial string for grouped tokens
-    # (schema/key/rule/hook). Called once from textus.rb after eager_load.
-    def self.build_cli_verbs
-      summaries = contract_summaries
-      CURATED_CLI_VERBS.map do |entry|
-        derived = summaries[entry["name"]]
-        derived ? entry.merge("summary" => derived) : entry
-      end
-    end
-
-    def self.agent_quickstart(manifest, audit_log)
-      agent_role = manifest.policy.proposer_role
-
-      writable_lanes = manifest.data.declared_lane_kinds.keys.each_with_object([]) do |lane_name, acc|
-        next unless agent_role
-
-        verb = manifest.policy.verb_for_lane(lane_name)
-        writers = manifest.policy.roles_with_capability(verb)
-        acc << lane_name if writers.include?(agent_role)
-      end
-
-      propose_lane = manifest.policy.propose_lane_for(agent_role)
-
-      {
-        "read_verbs" => Textus::Surface::MCP::Catalog.read_verbs,
-        "write_verbs" => agent_role ? Textus::Surface::MCP::Catalog.write_verbs : [],
-        "writable_lanes" => writable_lanes,
-        "propose_lane" => propose_lane,
-        "latest_seq" => audit_log.latest_seq,
-      }
-    end
-
-    def self.recipes(manifest)
-      queue = manifest.policy.queue_lane
-      feeds = lane_label(manifest, :machine, "the machine lane")
-      {
-        "read" => {
-          "purpose" => "find and read an entry",
-          "steps" => [
-            "list (lane:, prefix:) — discover keys without reading bodies",
-            "get KEY — returns the entry envelope",
-          ],
-        },
-        "write" => {
-          "purpose" => "create or update an entry",
-          "steps" => [
-            "schema KEY — learn the _meta field shape (required, optional, field types) before writing",
-            "assemble an envelope: { _meta: {…}, body: \"…\" }",
-            "put KEY — persist it (role-gated); pass if_etag to guard a concurrent edit",
-          ],
-        },
-        "propose" => {
-          "purpose" => "agent suggests a change for human review",
-          "agent_steps" => [
-            "propose KEY — writes the change into the #{queue} lane for review",
-          ],
-          "human_steps" => [
-            "accept #{queue}.KEY — promotes the proposal into its target lane",
-          ],
-        },
-        "drain" => {
-          "purpose" => "keep the machine-maintained lanes fresh — re-pull stale intake entries from their declared source",
-          "steps" => [
-            "pulse — its `stale` list names entries past their ttl",
-            "drain (lane: #{feeds}) — re-pull the stale entries",
-          ],
-        },
-      }
-    end
-
-    def self.agent_protocol(manifest)
-      AGENT_PROTOCOL_TEMPLATE.merge(
-        "recipes" => recipes(manifest),
-        "role_resolution" => {
-          "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
-                       "then a transport default ('human' for CLI, 'agent' for MCP)",
-          "roles" => manifest.data.role_caps.keys,
-          "ref" => "SPEC.md §5",
-        },
-      )
-    end
-
-    def self.build(container:)
-      manifest = container.manifest
-      etag = Textus::Value::Etag.for_contract(container.root)
-
-      {
-        "protocol" => PROTOCOL_ID,
-        "store_root" => container.root,
-        "contract_etag" => etag,
-        "lanes" => lanes_for(manifest),
-        "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
-        "orientation" => read_artifact_content(container, "artifacts.config.orientation"),
-        "context" => read_boot_context(container),
-        "agent_protocol" => agent_protocol(manifest),
-      }.compact
-    end
-
-    def self.read_artifact_content(container, key)
-      res = container.manifest.resolver.resolve(key)
-      return nil unless res.path && File.exist?(res.path)
-
-      call = Textus::Value::Call.build(role: Textus::Value::Role::DEFAULT)
-      env  = Textus::Action::Get.call(container: container, call: call, key: key)
-      env&.content
-    rescue Textus::Error
-      nil
-    end
-
-    def self.read_boot_context(container)
-      res = container.manifest.resolver.resolve("knowledge.boot")
-      return nil unless res.path && File.exist?(res.path)
-
-      call = Textus::Value::Call.build(role: Textus::Value::Role::DEFAULT)
-      env  = Textus::Action::Get.call(container: container, call: call, key: "knowledge.boot")
-      body = env&.body&.strip
-      body.nil? || body.empty? ? nil : body
-    rescue Textus::Error
-      nil
-    end
-
-    def self.lanes_for(manifest)
-      manifest.data.declared_lane_kinds.keys.map do |name|
-        verb = manifest.policy.verb_for_lane(name)
-        row = { "name" => name, "writers" => manifest.policy.roles_with_capability(verb) }
-        kind = manifest.policy.declared_kind(name)
-        row["kind"] = kind.to_s if kind
-        purpose = manifest.data.lane_descs[name]
-        row["purpose"] = purpose if purpose && !purpose.empty?
-        row
-      end
-    end
-  end
-end

data/lib/textus/contract/arg.rb

@@ -1,10 +0,0 @@
-module Textus
-  module Contract
-    Arg = Data.define(
-      :name, :type, :required, :positional, :session_default,
-      :description, :wire_name, :default, :source, :coerce, :cli_default
-    ) do
-      def wire = wire_name || name
-    end
-  end
-end

data/lib/textus/contract/dsl.rb

@@ -1,88 +0,0 @@
-module Textus
-  module Contract
-    module DSL
-      def verb(name = nil)
-        if name
-          raise "contract already built; declare verb before reading .contract" if defined?(@contract) && @contract
-
-          @__verb = name
-        else
-          @__verb
-        end
-      end
-
-      def summary(text = nil)
-        if text
-          raise "contract already built; declare summary before reading .contract" if defined?(@contract) && @contract
-
-          @__summary = text
-        else
-          @__summary
-        end
-      end
-
-      def surfaces(*list)
-        if list.empty?
-          @__surfaces ||= []
-        else
-          raise "contract already built; declare surfaces before reading .contract" if defined?(@contract) && @contract
-
-          @__surfaces = list
-        end
-      end
-
-      def cli(path = nil)
-        if path
-          raise "contract already built; declare cli before reading .contract" if defined?(@contract) && @contract
-
-          @__cli = path.to_s
-        else
-          @__cli
-        end
-      end
-
-      def arg(name, type, required: false, positional: false, session_default: nil, description: nil, wire_name: nil, default: nil, source: nil, coerce: nil, cli_default: :__unset) # rubocop:disable Metrics/ParameterLists,Layout/LineLength
-        raise "contract already built; declare args before reading .contract" if defined?(@contract) && @contract
-
-        (@__args ||= []) << Arg.new(
-          name: name, type: type, required: required,
-          positional: positional, session_default: session_default,
-          description: description, wire_name: wire_name, default: default,
-          source: source, coerce: coerce, cli_default: cli_default
-        )
-      end
-
-      def cli_stdin(mode = :__read)
-        return @__cli_stdin if mode == :__read
-
-        raise "contract already built; declare cli_stdin before reading .contract" if defined?(@contract) && @contract
-
-        @__cli_stdin = mode
-      end
-
-      def view(surface = :default, &blk)
-        return (@__views ||= {})[surface] unless blk
-
-        raise "contract already built; declare view before reading .contract" if defined?(@contract) && @contract
-
-        (@__views ||= {})[surface] = blk
-      end
-
-      def contract?
-        !@__verb.nil?
-      end
-
-      def contract
-        @contract ||= Spec.new(
-          verb: @__verb,
-          summary: @__summary,
-          args: (@__args || []).freeze,
-          surfaces: (@__surfaces || []).freeze,
-          views: ((@__views ||= {})[:default] ||= ->(v, _i) { v }) && @__views,
-          cli: @__cli,
-          cli_stdin: @__cli_stdin,
-        )
-      end
-    end
-  end
-end

data/lib/textus/contract/spec.rb

@@ -1,25 +0,0 @@
-module Textus
-  module Contract
-    Spec = Data.define(:verb, :summary, :args, :surfaces, :views, :cli, :cli_stdin) do
-      def mcp? = surfaces.include?(:mcp)
-      def cli? = surfaces.include?(:cli)
-
-      def view(surface = :default) = views[surface] || views.fetch(:default)
-      def cli_path = cli || verb.to_s
-      def cli_words = cli_path.split
-      def cli_group = cli_words.size > 1 ? cli_words.first : nil
-      def cli_leaf  = cli_words.last
-
-      def required_args = args.select(&:required)
-
-      def input_schema
-        props = args.to_h do |a|
-          h = { "type" => Contract.json_type(a.type) }
-          h["description"] = a.description if a.description
-          [a.wire.to_s, h]
-        end
-        { type: "object", properties: props, required: required_args.map { |a| a.wire.to_s } }
-      end
-    end
-  end
-end

data/lib/textus/contract.rb

@@ -1,12 +0,0 @@
-module Textus
-  module Contract
-    JSON_TYPES = {
-      String => "string", Integer => "integer", Hash => "object",
-      Array => "array", :boolean => "boolean"
-    }.freeze
-
-    def self.json_type(type)
-      JSON_TYPES.fetch(type) { raise ArgumentError.new("no JSON type mapping for #{type.inspect}") }
-    end
-  end
-end

data/lib/textus/core/freshness/evaluator.rb

@@ -1,150 +0,0 @@
-require "time"
-
-module Textus
-  module Core
-    module Freshness
-      # The single currency evaluator (ADR 0099). Answers "is the stored data
-      # stale relative to its retention rule?" and detects generator drift for
-      # external entries.
-      #   - retention rule TTL -> AGE signal: now - file_basis > ttl_seconds
-      #   - external -> DRIFT signal: a source changed since generated.at
-      #     (surfaced by the doctor generator_drift check).
-      class Evaluator
-        def initialize(manifest:, file_stat:, clock:)
-          @manifest  = manifest
-          @file_stat = file_stat
-          @clock     = clock
-        end
-
-        # Per-entry currency Verdict driven by the retention rule TTL (if any).
-        def verdict(mentry)
-          ttl = @manifest.rules.for(mentry.key).retention&.ttl_seconds
-          return fresh if ttl.nil?
-
-          stale = age_stale?(file_basis(mentry), ttl)
-          Verdict.build(stale: stale, reason: stale ? "ttl exceeded" : nil, fetching: false)
-        end
-
-        # Keys of entries past their retention rule TTL — the refresh produce scope.
-        def stale_keys(prefix: nil, lane: nil)
-          @manifest.data.entries.select { |m| due?(m, prefix: prefix, lane: lane) }.map(&:key)
-        end
-
-        alias stale_intake_keys stale_keys
-
-        # File basis as a Time (or nil): file mtime when present, else nil.
-        def file_basis(mentry)
-          path = @manifest.resolver.resolve(mentry.key).path
-          return nil unless @file_stat.exists?(path)
-
-          @file_stat.mtime(path)
-        end
-
-        # Generator-drift rows for one entry (replaces Staleness::GeneratorCheck#
-        # rows_for) — consumed by the doctor generator_drift check.
-        def drift_rows(mentry)
-          return [] unless drift_applicable?(mentry)
-
-          path = Textus::Key::Path.resolve(@manifest.data, mentry)
-          reason = drift_reason(mentry, path)
-          reason ? [drift_row(mentry, path, reason)] : []
-        end
-
-        private
-
-        def fresh = Verdict.build(stale: false, reason: nil, fetching: false)
-
-        def due?(mentry, prefix:, lane:)
-          return false if lane && mentry.lane != lane
-          return false if prefix && !mentry.key.start_with?(prefix)
-
-          ttl = @manifest.rules.for(mentry.key).retention&.ttl_seconds
-          return false if ttl.nil?
-
-          path = @manifest.resolver.resolve(mentry.key).path
-          return true unless @file_stat.exists?(path)
-
-          age_stale?(file_basis(mentry), ttl)
-        end
-
-        # The one age comparison. A never-recorded entry (nil basis) is stale.
-        def age_stale?(basis, ttl)
-          return true if basis.nil?
-
-          (@clock.now - basis).to_i > ttl
-        end
-
-        # --- generator drift (lifted from Staleness::GeneratorCheck) ---
-
-        def drift_applicable?(mentry) = mentry.external?
-
-        def drift_reason(mentry, path)
-          return "derived entry has never been generated" unless @file_stat.exists?(path)
-
-          generated_at = generated_at_of(mentry, path)
-          return "missing generated.at frontmatter" unless generated_at
-
-          gen_time = parse_time(generated_at)
-          return "unparseable generated.at: #{generated_at.inspect}" unless gen_time
-
-          offender = newest_source_after(mentry.source, gen_time)
-          "source '#{offender}' modified after generated.at" if offender
-        end
-
-        def generated_at_of(mentry, path)
-          Format.for(mentry.format).parse(@file_stat.read(path), path: path)["_meta"].dig("generated", "at")
-        end
-
-        def parse_time(str)
-          Time.parse(str.to_s)
-        rescue StandardError
-          nil
-        end
-
-        def newest_source_after(external_src, gen_time)
-          Array(external_src.sources).each do |src|
-            offender = check_source(src, gen_time)
-            return offender if offender
-          end
-          nil
-        end
-
-        def check_source(src, gen_time)
-          if src.match?(/\A[a-z0-9.][a-z0-9._-]*\z/) && !src.include?("/")
-            @manifest.resolver.enumerate(prefix: src).each do |row|
-              return src if @file_stat.mtime(row[:path]) > gen_time
-            end
-            nil
-          else
-            check_filesystem_source(src, gen_time)
-          end
-        end
-
-        def check_filesystem_source(src, gen_time)
-          abs = absolutize_source(src)
-          if @file_stat.directory?(abs)
-            dir_has_newer_file?(abs, gen_time) ? src : nil
-          elsif @file_stat.exists?(abs) && @file_stat.mtime(abs) > gen_time
-            src
-          end
-        end
-
-        def absolutize_source(src)
-          File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.data.root), src)
-        end
-
-        def dir_has_newer_file?(abs, gen_time)
-          @file_stat.glob(File.join(abs, "**", "*")).any? do |fpath|
-            file?(fpath) && @file_stat.mtime(fpath) > gen_time
-          end
-        end
-
-        def file?(fpath) = !@file_stat.directory?(fpath) && @file_stat.exists?(fpath)
-
-        def drift_row(mentry, path, reason)
-          { "key" => mentry.key, "path" => path, "generator" => mentry.source.command, "reason" => reason }
-        end
-      end
-    end
-  end
-end

data/lib/textus/core/freshness/verdict.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Core
-    module Freshness
-      # Value object describing the freshness annotation attached to an Envelope
-      # after a currency evaluation (ADR 0099 — was Core::Freshness).
-      #
-      # Note on wire format: `#to_h_for_wire` is intentionally narrower than the
-      # full field set. It emits the legacy keys ("stale", "stale_reason",
-      # "fetching", and "fetch_error" when present) so the CLI JSON wire stays
-      # byte-identical with textus/4. The gem-side fields `checked_at` and
-      # `ttl_remaining_ms` are NOT emitted on the wire.
-      Verdict = Data.define(
-        :stale, :fetching, :reason, :fetch_error, :checked_at, :ttl_remaining_ms
-      ) do
-        def self.build(stale:, fetching: false, reason: nil, fetch_error: nil,
-                       checked_at: nil, ttl_remaining_ms: nil)
-          new(
-            stale: stale, fetching: fetching, reason: reason,
-            fetch_error: fetch_error, checked_at: checked_at,
-            ttl_remaining_ms: ttl_remaining_ms
-          )
-        end
-
-        def to_h_for_wire
-          h = { "stale" => stale, "stale_reason" => reason, "fetching" => fetching }
-          h["fetch_error"] = fetch_error unless fetch_error.nil?
-          h
-        end
-      end
-    end
-  end
-end

data/lib/textus/core/freshness.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Core
-    # Currency — "is the stored data stale relative to its source?" (ADR 0099).
-    # The home of the single Freshness evaluator and its Verdict value object.
-    # Distinct from Core::Retention (GC dueness, Q2).
-    module Freshness
-    end
-  end
-end

data/lib/textus/core/retention/sweep.rb

@@ -1,57 +0,0 @@
-require "time"
-
-module Textus
-  module Core
-    module Retention
-      # Retention sweep reporter (ADR 0093/0099). Which entries are past their
-      # `retention:` ttl and the destructive action that applies. Age basis: file
-      # mtime. Only drop/archive. Renamed off the Core::Retention vs
-      # Manifest::Policy::Retention collision (ADR 0099).
-      class Sweep
-        def self.expired?(ttl_seconds:, mtime:, now:)
-          return false if ttl_seconds.nil? || mtime.nil?
-
-          (now - mtime).to_i > ttl_seconds
-        end
-
-        def initialize(manifest:, file_stat:, clock:)
-          @manifest = manifest
-          @file_stat = file_stat
-          @clock = clock
-        end
-
-        def call(prefix: nil, lane: nil)
-          @manifest.data.entries
-                   .select { |m| matches?(m, prefix: prefix, lane: lane) }
-                   .flat_map { |m| rows_for(m) }
-        end
-
-        private
-
-        def matches?(mentry, prefix:, lane:)
-          return false if lane && mentry.lane != lane
-          return false if prefix && !Textus::Key::Matching.matches_prefix?(
-            mentry.key, prefix, nested: mentry.is_a?(Textus::Manifest::Entry::Nested)
-          )
-
-          true
-        end
-
-        def rows_for(mentry)
-          policy = @manifest.rules.for(mentry.key).retention
-          return [] if policy.nil?
-
-          @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
-            path = row[:path]
-            next unless @file_stat.exists?(path)
-            next unless self.class.expired?(
-              ttl_seconds: policy.ttl_seconds, mtime: @file_stat.mtime(path), now: @clock.now,
-            )
-
-            { "key" => row[:key], "path" => path, "action" => policy.action.to_s }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/core/retention.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Core
-    # Retention — "is the entry old enough to retire?" (Q2, ADR 0093/0099).
-    # GC dueness, orthogonal to Freshness (content currency). The reporter is
-    # Core::Retention::Sweep; the manifest rule policy is Manifest::Policy::Retention.
-    module Retention
-    end
-  end
-end

data/lib/textus/core/sentinel.rb

@@ -1,30 +0,0 @@
-require "digest"
-
-module Textus
-  module Core
-    # Pure value object representing a published-file sentinel. Holds the
-    # recorded target path, source path, sha256 checksum, and publish mode.
-    # Has no filesystem I/O — path layout and persistence live in
-    # Ports::SentinelStore; predicate methods accept a FileStat port for
-    # existence and content checks.
-    class Sentinel
-      attr_reader :target, :source, :sha256, :mode
-
-      def initialize(target:, source:, sha256:, mode:)
-        @target = target
-        @source = source
-        @sha256 = sha256
-        @mode = mode
-      end
-
-      def orphan?(file_stat) = @target.nil? || !file_stat.exists?(@target)
-
-      def drift?(file_stat)
-        return false if orphan?(file_stat)
-        return false if @sha256.nil?
-
-        Digest::SHA256.hexdigest(file_stat.read(@target)) != @sha256
-      end
-    end
-  end
-end

data/lib/textus/doctor/check/audit_log.rb

@@ -1,34 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      class AuditLog < Check
-        def call
-          path = Textus::Store::Geometry.new(root).audit_log_path
-          Textus::Port::AuditLog.new(root).verify_integrity.map do |v|
-            {
-              "code" => "audit.parse_error",
-              "level" => "warning",
-              "subject" => "#{path}:#{v["lineno"]}",
-              "message" => violation_message(v),
-              "fix" => "inspect #{path} at line #{v["lineno"]} and remove the corrupted row",
-            }
-          end
-        end
-
-        private
-
-        def violation_message(v)
-          case v["reason"]
-          when "invalid_json"
-            "audit log line #{v["lineno"]} is invalid JSON: #{v["detail"]}"
-          when "short_tsv"
-            "audit log line #{v["lineno"]} #{v["detail"]} " \
-            "(consider migrating to NDJSON)"
-          else
-            v["detail"]
-          end
-        end
-      end
-    end
-  end
-end