textus 0.52.0 → 0.54.0

data/lib/textus/gate/auth.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Textus
+  class Gate
+    class Auth
+      FLOOR = {
+        put: %w[lane_writable_by raw_lane_ingest_only],
+        key_delete: %w[lane_deletable_by],
+        key_mv: %w[lane_writable_by raw_lane_ingest_only],
+        accept: %w[author_held],
+        reject: %w[author_held],
+        propose: %w[lane_writable_by raw_lane_ingest_only],
+        key_mv_prefix: %w[lane_writable_by raw_lane_ingest_only],
+        key_delete_prefix: %w[lane_writable_by raw_lane_ingest_only],
+        ingest: %w[lane_writable_by raw_write_once],
+      }.freeze
+
+      AuthContext = Struct.new(
+        :actor, :actor_caps, :lane_verb,
+        :action, :target, :envelope,
+        :mentry, :manifest,
+        keyword_init: true
+      )
+
+      def initialize(container)
+        @manifest = container.manifest
+        @schemas = container.schemas
+      end
+
+      # Command-based check (new Gate path).
+      def check!(cmd)
+        key = extract_key(cmd)
+        return unless key
+
+        evaluate_predicates(
+          action: command_to_action(cmd),
+          actor: cmd.role.to_s,
+          key: key,
+          envelope: nil,
+          extra: {},
+        )
+      end
+
+      # Backward-compatible check for inline action auth (accept, put, etc.).
+      def check_action!(action:, actor:, key:, envelope: nil, extra: {})
+        evaluate_predicates(
+          action: action.to_sym,
+          actor: actor,
+          key: key,
+          envelope: envelope,
+          extra: extra,
+        )
+      end
+
+      def self.command_to_verb
+        @command_to_verb ||= Textus::Gate::VERB_COMMAND.invert.freeze
+      end
+
+      private
+
+      def command_to_action(cmd)
+        self.class.command_to_verb.fetch(cmd.class) do
+          raise Textus::UsageError.new("unmapped command: #{cmd.class}")
+        end
+      end
+
+      def evaluate_predicates(action:, actor:, key:, envelope:, extra:)
+        mentry = @manifest.resolver.resolve(key).entry
+        lane_verb = @manifest.policy.verb_for_lane(mentry.lane.to_s)
+        actor_caps = Set.new(@manifest.data.role_caps.fetch(actor, []))
+
+        ctx = AuthContext.new(
+          actor:, actor_caps:, lane_verb:,
+          action:, target: key, envelope:,
+          mentry:, manifest: @manifest
+        )
+
+        failures = []
+        floor_preds = FLOOR.fetch(action, [])
+        rule_preds = rule_declared_predicates(action, key)
+        (floor_preds + rule_preds).uniq.each do |pred|
+          result = evaluate(pred, ctx, extra)
+          next if result[:pass]
+          raise result[:error] if result[:error]
+
+          failures << [pred, result[:reason]]
+        end
+        raise Textus::GuardFailed.new(failures) unless failures.empty?
+      end
+
+      def extract_key(cmd)
+        if cmd.respond_to?(:pending_key)
+          cmd.pending_key
+        elsif cmd.respond_to?(:key)
+          cmd.key
+        end
+      end
+
+      def rule_declared_predicates(action, key)
+        guard_map = @manifest.rules.for(key).guard
+        return [] if guard_map.nil?
+
+        Array(guard_map[action.to_s])
+      end
+
+      def evaluate(pred_name, ctx, extra)
+        case pred_name
+        when "lane_writable_by"      then evaluate_lane_writable_by(ctx)
+        when "author_held"           then evaluate_author_held(ctx)
+        when "target_is_canon"       then evaluate_target_is_canon(ctx)
+        when "etag_match"            then evaluate_etag_match(ctx, extra)
+        when "schema_valid"          then evaluate_schema_valid(ctx)
+        when "fresh_within"          then { pass: true }
+        when "raw_lane_ingest_only"  then evaluate_raw_lane_ingest_only(ctx)
+        when "raw_write_once"        then evaluate_raw_write_once(ctx)
+        when "lane_deletable_by"     then evaluate_lane_deletable_by(ctx)
+        else raise Textus::UsageError.new("unknown predicate '#{pred_name}'")
+        end
+      end
+
+      def evaluate_lane_writable_by(ctx)
+        pass = ctx.actor_caps.include?(ctx.lane_verb.to_s)
+        return { pass: true } if pass
+
+        holders = @manifest.policy.roles_with_capability(ctx.lane_verb.to_s)
+        { pass: false, error: Textus::WriteForbidden.new(ctx.mentry.key, ctx.mentry.lane, verb: ctx.lane_verb, holders:) }
+      end
+
+      def evaluate_author_held(ctx)
+        holders = @manifest.policy.roles_with_capability("author")
+        pass = holders.include?(ctx.actor.to_s)
+        reason = if pass
+                   nil
+                 elsif holders.empty?
+                   "no role holds the 'author' capability; #{ctx.action} is disabled"
+                 else
+                   "role '#{ctx.actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
+                 end
+        { pass:, reason: }
+      end
+
+      def evaluate_target_is_canon(ctx)
+        kind = @manifest.policy.declared_kind(ctx.mentry.lane.to_s)
+        pass = kind == :canon
+        { pass:, reason: pass ? nil : "target lane '#{ctx.mentry.lane}' is not canon (kind: #{kind})" }
+      end
+
+      def evaluate_etag_match(ctx, extra)
+        if_etag = extra[:if_etag]
+        return { pass: true } if if_etag.nil?
+
+        current = ctx.envelope&.etag
+        pass = current.nil? || current == if_etag
+        { pass:, error: pass ? nil : Textus::EtagMismatch.new(ctx.target, if_etag, current) }
+      end
+
+      def evaluate_schema_valid(ctx)
+        return { pass: true } unless ctx.envelope
+
+        schema_ref = ctx.mentry.schema
+        return { pass: true } unless schema_ref
+
+        schema = @schemas.fetch_or_nil(schema_ref)
+        return { pass: true } unless schema
+
+        frontmatter = ctx.envelope.meta&.dig("_meta") || ctx.envelope.meta || {}
+        begin
+          schema.validate!(frontmatter)
+          { pass: true }
+        rescue Textus::SchemaViolation => e
+          { pass: false, reason: schema_reason(e) }
+        end
+      end
+
+      def evaluate_raw_lane_ingest_only(ctx)
+        return { pass: true } unless @manifest.policy.declared_kind(ctx.mentry.lane.to_s) == :raw
+        return { pass: true } if ctx.action == :ingest
+
+        { pass: false, error: Textus::Error.new(
+          :raw_lane_ingest_only,
+          "raw lane '#{ctx.mentry.lane}' only accepts `textus ingest` — " \
+          "use that verb instead of '#{ctx.action}'",
+        ) }
+      end
+
+      def evaluate_raw_write_once(ctx)
+        path = @manifest.resolver.resolve(ctx.target).path
+        return { pass: true } unless File.exist?(path)
+
+        { pass: false, error: Textus::Error.new(
+          :raw_write_once,
+          "raw entry '#{ctx.target}' already exists; " \
+          "delete it first (`textus key-delete #{ctx.target}`), then re-ingest",
+        ) }
+      end
+
+      # Deletion authority: the lane's write capability OR the author capability.
+      # On raw-kind lanes only the author capability grants deletion (correction
+      # escape hatch); the lane's own verb (ingest) is write-only. On all other
+      # lane kinds the behaviour matches lane_writable_by — the lane's writer
+      # can delete as before.
+      def evaluate_lane_deletable_by(ctx)
+        is_raw = @manifest.policy.declared_kind(ctx.mentry.lane.to_s) == :raw
+        pass = if is_raw
+                 ctx.actor_caps.include?("author")
+               else
+                 ctx.actor_caps.include?(ctx.lane_verb.to_s) || ctx.actor_caps.include?("author")
+               end
+        return { pass: true } if pass
+
+        extra_holders = is_raw ? ["author"] : [ctx.lane_verb.to_s, "author"]
+        holders = extra_holders.flat_map { |v| @manifest.policy.roles_with_capability(v) }.uniq
+        { pass: false, error: Textus::WriteForbidden.new(ctx.mentry.key, ctx.mentry.lane,
+                                                         verb: ctx.lane_verb, holders:) }
+      end
+
+      def schema_reason(err)
+        d = err.details
+        return err.message.dup unless d.is_a?(Hash)
+        return "missing required fields: #{Array(d["missing"]).join(", ")}" if d["missing"]
+        return "field '#{d["field"]}': #{d["reason"]}" if d["field"]
+
+        err.message.dup
+      end
+    end
+  end
+end

data/lib/textus/gate.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Textus
+  class Gate
+    VERB_COMMAND = {
+      get: Textus::Command::Get,
+      put: Textus::Command::Put,
+      propose: Textus::Command::Propose,
+      key_delete: Textus::Command::KeyDelete,
+      key_mv: Textus::Command::KeyMv,
+      accept: Textus::Command::Accept,
+      reject: Textus::Command::Reject,
+      enqueue: Textus::Command::Enqueue,
+      list: Textus::Command::List,
+      where: Textus::Command::Where,
+      uid: Textus::Command::Uid,
+      blame: Textus::Command::Blame,
+      audit: Textus::Command::Audit,
+      deps: Textus::Command::Deps,
+      rdeps: Textus::Command::Rdeps,
+      pulse: Textus::Command::Pulse,
+      rule_explain: Textus::Command::RuleExplain,
+      rule_list: Textus::Command::RuleList,
+      rule_lint: Textus::Command::RuleLint,
+      published: Textus::Command::Published,
+      schema_show: Textus::Command::SchemaShow,
+      doctor: Textus::Command::Doctor,
+      boot: Textus::Command::Boot,
+      jobs: Textus::Command::Jobs,
+      data_mv: Textus::Command::DataMv,
+      key_mv_prefix: Textus::Command::KeyMvPrefix,
+      key_delete_prefix: Textus::Command::KeyDeletePrefix,
+      drain: Textus::Command::Drain,
+      ingest: Textus::Command::Ingest,
+    }.freeze
+
+    ROUTES = {
+      Command::Get => [Textus::Action::Get],
+      Command::Put => [Textus::Action::Put],
+      Command::Propose => [Textus::Action::Propose],
+      Command::KeyDelete => [Textus::Action::KeyDelete],
+      Command::KeyMv => [Textus::Action::KeyMv],
+      Command::Accept => [Textus::Action::Accept],
+      Command::Reject => [Textus::Action::Reject],
+      Command::Enqueue => [Textus::Action::Enqueue],
+      Command::List => [Textus::Action::List],
+      Command::Where => [Textus::Action::Where],
+      Command::Uid => [Textus::Action::Uid],
+      Command::Blame => [Textus::Action::Blame],
+      Command::Audit => [Textus::Action::Audit],
+      Command::Deps => [Textus::Action::Deps],
+      Command::Rdeps => [Textus::Action::Rdeps],
+      Command::Pulse => [Textus::Action::Pulse],
+      Command::RuleExplain => [Textus::Action::RuleExplain],
+      Command::RuleList => [Textus::Action::RuleList],
+      Command::RuleLint => [Textus::Action::RuleLint],
+      Command::Published => [Textus::Action::Published],
+      Command::SchemaShow => [Textus::Action::SchemaEnvelope],
+      Command::Doctor => [Textus::Action::Doctor],
+      Command::Boot => [Textus::Action::Boot],
+      Command::Jobs => [Textus::Action::Jobs],
+      Command::DataMv => [Textus::Action::DataMv],
+      Command::KeyMvPrefix => [Textus::Action::KeyMvPrefix],
+      Command::KeyDeletePrefix => [Textus::Action::KeyDeletePrefix],
+      Command::Drain => [Textus::Action::Drain],
+      Command::Ingest => [Textus::Action::Ingest],
+    }.freeze
+
+    def initialize(container)
+      @container = container
+    end
+
+    def dispatch(cmd, correlation_id: nil)
+      cmd = normalize_propose_key(cmd, @container) if cmd.is_a?(Command::Propose)
+      action_classes = ROUTES.fetch(cmd.class) do
+        raise Textus::UsageError.new("unknown command: #{cmd.class}")
+      end
+
+      Gate::Auth.new(@container).check!(cmd)
+      call_obj = build_call(cmd, correlation_id: correlation_id)
+      results = action_classes.map { |klass| run_action(klass, cmd, @container, call_obj) }
+      results.length == 1 ? results.first : results
+    end
+
+    private
+
+    def normalize_propose_key(cmd, container)
+      return cmd if cmd.pending_key
+
+      zone = container.manifest.policy.propose_lane_for(cmd.role.to_s)
+      cmd.with(pending_key: zone ? "#{zone}.#{cmd.key}" : nil)
+    end
+
+    def run_action(klass, cmd, container, call_obj)
+      action = klass.new(**extract_kwargs(klass, cmd))
+      action.call(container:, call: call_obj)
+    end
+
+    def extract_kwargs(klass, cmd)
+      params = klass.instance_method(:initialize).parameters
+      accepts_keyrest = params.any? { |t, _| t == :keyrest }
+      param_set = params.to_set { |_t, n| n }
+      cmd.members.each_with_object({}) do |m, h|
+        next unless accepts_keyrest || param_set.include?(m)
+
+        val = cmd.public_send(m)
+        h[m] = val unless val.nil?
+      end
+    end
+
+    def build_call(cmd, correlation_id: nil)
+      dry_run = cmd.respond_to?(:dry_run) ? !cmd.dry_run.nil? : false
+      Textus::Call.build(role: cmd.role, dry_run:, correlation_id: correlation_id)
+    end
+  end
+end

data/lib/textus/init.rb

@@ -3,7 +3,7 @@ require "pathname"
 
 module Textus
   module Init
-    ZONES = %w[knowledge notebook proposals artifacts].freeze
+    ZONES = %w[knowledge notebook proposals artifacts raw].freeze
 
     DEFAULT_MANIFEST = <<~YAML
       version: textus/3
@@ -11,143 +11,97 @@ module Textus
         - { name: human,      can: [author, propose] }
         - { name: agent,      can: [propose, keep] }
         - { name: automation, can: [converge] }
-      zones:
+      lanes:
         - { name: knowledge, kind: canon,     desc: "the maintained source of truth (identity.* lives here)" }
         - { name: notebook,  kind: workspace, owner: agent, desc: "the agent's own durable working notes" }
         - { name: proposals, kind: queue,     desc: "changes awaiting your accept" }
         - { name: artifacts, kind: machine,   desc: "machine-maintained: external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)" }
       entries:
-        - { key: knowledge.identity, path: knowledge/identity.md, zone: knowledge, schema: null, owner: human:self, kind: leaf }
-        - { key: knowledge.notes,    path: knowledge/notes,       zone: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
-        - { key: notebook.notes,     path: notebook/notes,        zone: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
-        - { key: proposals.notes,    path: proposals/notes,       zone: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
-        # A per-host snapshot, refreshed from its declared intake by `textus drain` (scheduled, or on demand).
-        # Nested so it grows to a fleet — add artifacts.feeds.machines.<host> leaves over SSH
-        # (see docs/cookbook/environment-scan.md) without renaming. tracked:false →
+        - { key: knowledge.identity, path: data/knowledge/identity.md, lane: knowledge, schema: null, owner: human:self, kind: leaf }
+        - { key: knowledge.notes,    path: data/knowledge/notes,       lane: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
+        - { key: notebook.notes,     path: data/notebook/notes,        lane: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
+        - { key: proposals.notes,    path: data/proposals/notes,       lane: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
+        # A per-host snapshot, populated by a registered workflow. Nested so it
+        # grows to a fleet — add leaves over SSH without renaming. tracked:false →
         # gitignored (machine info can be sensitive/noisy) but still protocol-readable
         # via `textus get artifacts.feeds.machines.local`. Delete to opt out. (ADR 0043)
         - key: artifacts.feeds.machines
-          path: artifacts/feeds/machines
-          zone: artifacts
+          path: data/artifacts/feeds/machines
+          lane: artifacts
           format: yaml
           nested: true
           tracked: false
-          kind: produced
-          source:
-            from: handler
-            handler: machines
-            ttl: 1h # cadence on a long-running server
-            config:
-              machines:
-                local: { via: local }
+          kind: nested
       rules: []
     YAML
 
-    HOOKS_README = <<~MD
-      # Hooks
-
-      Drop one Ruby file per hook. All hooks register through one DSL.
-      Files anywhere under `.textus/hooks/` (including subdirectories) are loaded at
-      startup in alphabetical order by full path. Subdirectory names are organizational
-      only — the registered event and name come from the DSL call, not the file path.
-
-      ## DSL
-
-      ```ruby
-      Textus.hook do |reg|
-        reg.on(:resolve_handler, :my_source) do |config:, args:, **|
-          { _meta: { "last_fetched_at" => Time.now.utc.iso8601 }, body: "…" }
-        end
-
-        reg.on(:transform_rows, :my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
-        reg.on(:validate,       :my_check)  { |caps:, **| [] }
-        reg.on(:entry_written,      :my_listener, keys: ["knowledge.*"]) { |key:, envelope:, **| }
-
-        # Run a side-effect every time textus writes a file to your repo:
-        reg.on(:entry_published, :notify) do |key:, target:, **|
-          warn "wrote \#{target} (from \#{key})"
-        end
-      end
-      ```
-
-      The intake handler above is paired with a manifest entry whose
-      `source:` block declares the handler and its refresh cadence
-      (`ttl`). Age GC (drop/archive) lives in a top-level `retention:`
-      rule, not on the entry:
-
-      ```yaml
-      entries:
-        - key: artifacts.feeds.foo
-          kind: produced
-          path: artifacts/feeds/foo.md
-          zone: artifacts
-          source:
-            from: handler
-            handler: my_source
-            ttl: 10m        # refresh cadence for this intake
-
-      rules:
-        - match: artifacts.feeds.foo
-          retention:
-            ttl: 30d
-            action: archive   # drop | archive (age GC of stored rows)
-      ```
-
-      Events: :resolve_handler, :transform_rows, :validate (rpc — return value used)
-              :entry_written, :entry_deleted, :entry_fetched, :entry_renamed,
-              :entry_produced, :produce_failed,
-              :proposal_accepted, :proposal_rejected,
-              :entry_published, :store_loaded, :session_opened,
-              :entry_fetch_started, :entry_fetch_failed (pub-sub — return discarded)
-
-      See SPEC.md §5.10 for the full table.
-    MD
-
     AGENT_ENTRIES = <<~YAML.gsub(/^/, "  ")
-      # --with-agent profile: project facts + runbooks feed the orientation
-      # projection below, which `textus drain` renders to CLAUDE.md/AGENTS.md.
-      - { key: knowledge.project, path: knowledge/project.md, zone: knowledge, schema: project, owner: human:self, kind: leaf }
-      - { key: knowledge.runbooks, path: knowledge/runbooks, zone: knowledge, schema: runbook, owner: human:self, nested: true, kind: nested }
+      - { key: knowledge.project, path: data/knowledge/project.md, lane: knowledge, schema: project, owner: human:self, kind: leaf }
+      - { key: knowledge.runbooks, path: data/knowledge/runbooks, lane: knowledge, schema: runbook, owner: human:self, nested: true, kind: nested }
       - key: artifacts.derived.orientation
-        path: artifacts/derived/orientation.json
-        zone: artifacts
+        path: data/artifacts/derived/orientation.json
+        lane: artifacts
         publish:
         - { to: CLAUDE.md, template: orientation.mustache, inject_boot: true }
         - { to: AGENTS.md, template: orientation.mustache, inject_boot: true }
-        source:
-          from: project
-          select:
-          - knowledge.project
-          - knowledge.runbooks
-          transform: orientation_reducer
         kind: produced
     YAML
 
     def self.run(target_root, with_agent: false)
+      check_target!(target_root)
+      scaffold_dir = File.expand_path("init/templates", __dir__)
+      create_directories(target_root)
+      write_manifest(target_root, with_agent:)
+      mcp_status = scaffold_agent(target_root, scaffold_dir, with_agent:)
+      setup_state_dirs(target_root)
+      write_gitignore(target_root)
+      build_result(target_root, with_agent:, mcp_status:)
+    end
+
+    def self.check_target!(target_root)
       raise UsageError.new(".textus/ already exists at #{target_root}") if File.directory?(target_root)
+    end
+
+    ASSET_ZONES = %w[raw].freeze
 
+    def self.create_directories(target_root)
       FileUtils.mkdir_p(File.join(target_root, "schemas"))
       FileUtils.mkdir_p(File.join(target_root, "templates"))
-      FileUtils.mkdir_p(File.join(target_root, "hooks"))
+      FileUtils.mkdir_p(File.join(target_root, "workflows"))
       ZONES.each do |z|
-        dir = File.join(target_root, "zones", z)
+        dir = File.join(target_root, "data", z)
         FileUtils.mkdir_p(dir)
         File.write(File.join(dir, ".gitkeep"), "")
       end
-      File.write(File.join(target_root, "hooks", "README.md"), HOOKS_README)
-      scaffold_dir = File.expand_path("init/templates", __dir__)
-      File.write(File.join(target_root, "hooks", "machine_intake.rb"),
-                 File.read(File.join(scaffold_dir, "machine_intake.rb")))
-      File.write(File.join(target_root, "manifest.yaml"), manifest_yaml(with_agent: with_agent))
-      mcp_status = nil
-      if with_agent
-        scaffold_agent_profile(target_root, scaffold_dir)
-        mcp_status = write_mcp_config(target_root, scaffold_dir)
+      ASSET_ZONES.each do |z|
+        dir = File.join(target_root, "assets", z)
+        FileUtils.mkdir_p(dir)
+        File.write(File.join(dir, ".gitkeep"), "")
       end
+    end
+
+    def self.write_manifest(target_root, with_agent:)
+      File.write(File.join(target_root, "manifest.yaml"), manifest_yaml(with_agent: with_agent))
+    end
+
+    def self.scaffold_agent(target_root, scaffold_dir, with_agent:)
+      return nil unless with_agent
+
+      scaffold_agent_profile(target_root, scaffold_dir)
+      write_mcp_config(target_root, scaffold_dir)
+    end
+
+    def self.setup_state_dirs(target_root)
       FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
       FileUtils.mkdir_p(Textus::Layout.state(target_root))
       FileUtils.mkdir_p(Textus::Layout.locks(target_root))
+    end
+
+    def self.write_gitignore(target_root)
       File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
+    end
+
+    def self.build_result(target_root, with_agent:, mcp_status:)
       result = { "protocol" => PROTOCOL, "initialized" => target_root, "profile" => with_agent ? "agent" : "default" }
       result["mcp_config"] = mcp_status if with_agent
       result
@@ -168,7 +122,6 @@ module Textus
         "project.schema.yaml" => File.join("schemas", "project.yaml"),
         "runbook.schema.yaml" => File.join("schemas", "runbook.yaml"),
         "orientation.mustache" => File.join("templates", "orientation.mustache"),
-        "orientation_reducer.rb" => File.join("hooks", "orientation_reducer.rb"),
       }.each do |src, dest|
         File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
       end
@@ -193,8 +146,9 @@ module Textus
       manifest = Textus::Manifest.load(target_root)
       root = Pathname.new(target_root)
       untracked = manifest.data.entries.reject(&:tracked?).map do |e|
-        if e.nested? # a whole subtree of leaf files (artifacts.feeds.machines.* → zones/artifacts/feeds/machines/)
-          "#{File.join("zones", e.path)}/"
+        if e.nested? # a whole subtree of leaf files (artifacts.feeds.machines.* → data/artifacts/feeds/machines/)
+          rel = e.path.start_with?("data/") ? e.path : File.join("data", e.path)
+          "#{rel}/"
         else
           Pathname.new(Textus::Key::Path.resolve(manifest.data, e)).relative_path_from(root).to_s
         end

data/lib/textus/jobs/base.rb

@@ -0,0 +1,23 @@
+module Textus
+  module Jobs
+    class Base
+      def self.inherited(subclass)
+        super
+        return unless subclass.name
+
+        TracePoint.new(:end) do |tp|
+          if tp.self == subclass
+            Textus::Jobs.register(subclass)
+            tp.disable
+          end
+        end.enable
+      end
+
+      def call(**)
+        raise NotImplementedError.new("#{self.class}#call")
+      end
+
+      def args = {}
+    end
+  end
+end

data/lib/textus/jobs/materialize.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Textus
+  module Jobs
+    class Materialize < Base
+      TYPE = "materialize"
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def args = { key: @key }
+
+      def call(container:, call:)
+        Textus::Produce::Engine.converge(container: container, call: call, keys: [@key])
+      end
+    end
+  end
+end

data/lib/textus/jobs/plan.rb

@@ -0,0 +1,9 @@
+module Textus
+  module Jobs
+    Plan = Data.define(:steps, :warnings) do
+      def to_h
+        { "steps" => steps, "warnings" => warnings }
+      end
+    end
+  end
+end