textus 0.53.0 → 0.54.0

data/lib/textus/envelope/writer.rb

@@ -0,0 +1,209 @@
+require "fileutils"
+
+module Textus
+  class Envelope
+    # Owns the write pipeline (validate, serialize, etag-check, write, audit).
+    # Talks to ports (FileStore, Schemas, AuditLog, Manifest) and an
+    # Reader for the existing-uid lookup.
+    #
+    # Invariant: every public method's final action is @audit_log.append(...).
+    #
+    # No permission check, no event firing — those belong to the caller
+    # (Write::Put / ::Delete / ::Mv).
+    class Writer
+      Payload = Data.define(:meta, :body, :content)
+
+      def self.from(container:, call:)
+        new(
+          file_store: container.file_store, manifest: container.manifest,
+          schemas: container.schemas, audit_log: container.audit_log,
+          call: call, reader: Reader.from(container: container)
+        )
+      end
+
+      def initialize(file_store:, manifest:, schemas:, audit_log:, call:, reader:)
+        @file_store = file_store
+        @manifest   = manifest
+        @schemas    = schemas
+        @audit_log  = audit_log
+        @call       = call
+        @reader     = reader
+      end
+
+      def put(key, mentry:, payload:, if_etag: nil)
+        path = resolve_path(key)
+        meta, content = prepare_uid(mentry, payload, key)
+        bytes, eff_meta, eff_body, eff_content = serialize_entry(mentry, path, meta, payload, content)
+        enforce_name_match!(path, eff_meta, mentry.format)
+        validate_schema(mentry, eff_meta, eff_content)
+        etag_before = check_etag!(path, key, if_etag)
+        write_bytes(path, bytes)
+        envelope = build_envelope(key, mentry, path, eff_meta, eff_body, eff_content)
+        audit_put(key, etag_before, envelope.etag)
+        envelope
+      end
+
+      def delete(key, mentry: nil, if_etag: nil) # rubocop:disable Lint/UnusedMethodArgument
+        # `mentry:` is accepted for symmetry with `put` / `move` and to
+        # leave room for future format-specific delete hooks; no field
+        # on it is needed today.
+        path = @manifest.resolver.resolve(key).path
+        raise UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)) unless @file_store.exists?(path)
+
+        etag_before = @file_store.etag(path)
+        raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && if_etag != etag_before
+
+        @file_store.delete(path)
+        prune_empty_parents(path)
+        @audit_log.append(
+          role: @call.role, verb: "key_delete", key: key,
+          etag_before: etag_before, etag_after: nil,
+          extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
+        )
+      end
+
+      def move(from_key:, to_key:, new_mentry:, if_etag: nil)
+        from_path = @manifest.resolver.resolve(from_key).path
+        to_path   = @manifest.resolver.resolve(to_key).path
+        raise UnknownKey.new(from_key, suggestions: @manifest.resolver.suggestions_for(from_key)) unless @file_store.exists?(from_path)
+
+        etag_before = @file_store.etag(from_path)
+        raise EtagMismatch.new(from_key, if_etag, etag_before) if if_etag && if_etag != etag_before
+
+        FileUtils.mkdir_p(File.dirname(to_path))
+        FileUtils.mv(from_path, to_path)
+        prune_empty_parents(from_path)
+        basename = to_key.split(".").last
+        Format.for(new_mentry.format).rewrite_name(to_path, basename)
+        etag_after = Etag.for_file(to_path)
+
+        raw = @file_store.read(to_path)
+        parsed = Format.for(new_mentry.format).parse(raw, path: to_path)
+        envelope = Textus::Envelope.build(
+          key: to_key, mentry: new_mentry, path: to_path,
+          meta: parsed["_meta"], body: parsed["body"],
+          etag: etag_after, content: parsed["content"]
+        )
+
+        extras = {
+          "from_key" => from_key, "to_key" => to_key,
+          "from_path" => from_path, "to_path" => to_path,
+          "uid" => envelope.uid
+        }
+        extras["correlation_id"] = @call.correlation_id if @call.correlation_id
+
+        @audit_log.append(
+          role: @call.role, verb: "key_mv", key: to_key,
+          etag_before: etag_before, etag_after: etag_after,
+          extras: extras
+        )
+
+        envelope
+      end
+
+      private
+
+      # After a file leaves a directory (delete or move-source), remove any
+      # now-empty parent dirs so bulk move/delete doesn't accrue orphan dirs
+      # (F3 of #161). Floored at the entry's *zone directory* — a zone is a
+      # declared, first-class container, so its own dir is preserved even when
+      # momentarily empty; only the sub-dirs the bulk op carved out are
+      # pruned. Stops at the first non-empty ancestor, so a dir holding a
+      # `.gitkeep` or sibling entries survives. Best-effort: a lost race or a
+      # non-empty dir is silently fine, never fatal to the write.
+      def prune_empty_parents(path)
+        floor = zone_floor(path)
+        return unless floor
+
+        dir = File.dirname(path)
+        while dir.start_with?("#{floor}/") && Dir.empty?(dir)
+          Dir.rmdir(dir)
+          dir = File.dirname(dir)
+        end
+      rescue SystemCallError
+        nil
+      end
+
+      # The zone directory under which `path` lives (`<root>/zones/<zone>`),
+      # or nil if `path` is not under the store's zones tree.
+      def zone_floor(path)
+        zones_root = File.join(@manifest.data.root, "data")
+        prefix = "#{zones_root}/"
+        return nil unless path.start_with?(prefix)
+
+        zone_seg = path.delete_prefix(prefix).split("/").first
+        zone_seg && File.join(zones_root, zone_seg)
+      end
+
+      def ensure_uid(format, meta, content, existing_uid)
+        Textus::Format.for(format).inject_uid(meta, content, existing_uid)
+      end
+
+      def enforce_name_match!(path, meta, format)
+        Textus::Format.for(format).enforce_name_match!(path, meta)
+      end
+
+      def serialize_for_put(mentry:, path:, meta:, body:, content:)
+        Textus::Format.for(mentry.format).serialize_for_put(
+          meta: meta, body: body, content: content, path: path,
+        )
+      end
+
+      def resolve_path(key)
+        @manifest.resolver.resolve(key).path
+      end
+
+      def prepare_uid(mentry, payload, key)
+        meta = payload.meta || {}
+        existing_uid = @reader.existing_uid(key)
+        ensure_uid(mentry.format, meta, payload.content, existing_uid)
+      end
+
+      def serialize_entry(mentry, path, meta, payload, content)
+        serialize_for_put(
+          mentry: mentry, path: path,
+          meta: meta, body: payload.body, content: content
+        )
+      end
+
+      def validate_schema(mentry, eff_meta, eff_content)
+        schema = @schemas.fetch_or_nil(mentry.schema)
+        return unless schema
+
+        Format.for(mentry.format).validate_against(
+          schema,
+          { "_meta" => eff_meta, "content" => eff_content },
+        )
+      end
+
+      def check_etag!(path, key, if_etag)
+        etag_before = @file_store.exists?(path) ? @file_store.etag(path) : nil
+        raise EtagMismatch.new(key, if_etag, etag_before) if if_etag && (etag_before != if_etag)
+
+        etag_before
+      end
+
+      def write_bytes(path, bytes)
+        @file_store.write(path, bytes)
+      end
+
+      def build_envelope(key, mentry, path, eff_meta, eff_body, eff_content)
+        Textus::Envelope.build(
+          key: key, mentry: mentry, path: path,
+          meta: eff_meta, body: eff_body,
+          etag: Etag.for_bytes(@file_store.read(path)),
+          content: eff_content
+        )
+      end
+
+      def audit_put(key, etag_before, etag_after)
+        extras = @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
+        @audit_log.append(
+          role: @call.role, verb: "put", key: key,
+          etag_before: etag_before, etag_after: etag_after,
+          extras: extras
+        )
+      end
+    end
+  end
+end

data/lib/textus/errors.rb

@@ -158,10 +158,6 @@ module Textus
     end
   end
 
-  class InvalidProjection < Error
-    def initialize(m) = super("invalid_projection", m)
-  end
-
   class TemplateError < Error
     def initialize(m, template_name: nil)
       hint =
@@ -209,6 +205,14 @@ module Textus
     end
   end
 
+  class ContractDrift < Error
+    JSONRPC_CODE = -32_001
+
+    def initialize(message, details: {})
+      super("contract_drift", message, details: details)
+    end
+  end
+
   class FlagRenamed < Error
     def initialize(old_flag, new_flag)
       super(

data/lib/textus/{entry → format}/base.rb

@@ -1,8 +1,5 @@
 module Textus
-  module Entry
-    # Abstract base for entry format strategies. Each concrete strategy
-    # owns parsing, serialization, file-extension claims, and schema
-    # validation for entries declared with its format.
+  module Format
     class Base
       def self.parse(_raw, path: nil)
         _ = path
@@ -20,8 +17,6 @@ module Textus
         raise NotImplementedError.new("#{name}.extensions not implemented")
       end
 
-      # Default: validate the meta hash. Overridden by formats that put the
-      # validatable payload elsewhere (json/yaml put it under "content").
       def self.validate_against(schema, parsed)
         schema.validate!(parsed["_meta"] || {})
       end

data/lib/textus/{entry → format}/json.rb

@@ -1,8 +1,7 @@
 require "json"
 
 module Textus
-  module Entry
-    # JSON entry storage. Top-level must be an object so we can carry _meta.
+  module Format
     class Json < Base
       def self.parse(raw, path: nil)
         raw = raw.dup.force_encoding(Encoding::UTF_8)
@@ -23,7 +22,6 @@ module Textus
 
       def self.serialize(meta:, body:, content: nil)
         if content.is_a?(Hash)
-          # Re-inject _meta as the first key so on-disk shape is stable.
           on_disk = meta && !meta.empty? ? { "_meta" => meta }.merge(content) : content
           out = ::JSON.pretty_generate(on_disk)
           out += "\n" unless out.end_with?("\n")
@@ -61,7 +59,6 @@ module Textus
         end
       end
 
-      # Mutating filesystem op; returns true if a write happened.
       def self.rewrite_name(path, basename) # rubocop:disable Naming/PredicateMethod
         raw = File.binread(path)
         parsed = parse(raw, path: path)

data/lib/textus/{entry → format}/markdown.rb

@@ -1,8 +1,7 @@
 require "yaml"
 
 module Textus
-  module Entry
-    # Markdown with YAML frontmatter. Original Entry implementation.
+  module Format
     class Markdown < Base
       def self.parse(raw, path: nil)
         raw = raw.dup.force_encoding(Encoding::UTF_8)
@@ -26,7 +25,7 @@ module Textus
       end
 
       def self.serialize(meta:, body:, content: nil)
-        _ = content # markdown ignores content
+        _ = content
         fm_yaml = meta.empty? ? "" : ::YAML.dump(meta).sub(/\A---\n/, "")
         body = body.to_s
         body += "\n" unless body.empty? || body.end_with?("\n")
@@ -44,9 +43,6 @@ module Textus
         [bytes, meta, body.to_s, nil]
       end
 
-      # Mutating filesystem op; returns true if a write happened (boolean is
-      # informational, not a predicate). Rubocop's predicate-name heuristic
-      # disabled here on purpose.
       def self.rewrite_name(path, basename) # rubocop:disable Naming/PredicateMethod
         raw = File.binread(path)
         parsed = parse(raw, path: path)

data/lib/textus/{entry → format}/text.rb

@@ -1,6 +1,5 @@
 module Textus
-  module Entry
-    # Plain-text entry storage. No frontmatter or structured content.
+  module Format
     class Text < Base
       def self.parse(raw, path: nil)
         raw = raw.dup.force_encoding(Encoding::UTF_8)
@@ -25,9 +24,7 @@ module Textus
         [meta, content]
       end
 
-      def self.enforce_name_match!(_path, _meta)
-        # text has no meta home; no-op
-      end
+      def self.enforce_name_match!(_path, _meta); end
 
       def self.serialize_for_put(meta:, body:, content:, path:)
         _ = path
@@ -36,7 +33,6 @@ module Textus
         [bytes, meta, body.to_s, nil]
       end
 
-      # No-op; text has no meta. Returns false (never writes).
       def self.rewrite_name(_path, _basename) # rubocop:disable Naming/PredicateMethod
         false
       end

data/lib/textus/{entry → format}/yaml.rb

@@ -1,8 +1,7 @@
 require "yaml"
 
 module Textus
-  module Entry
-    # YAML entry storage. Top-level must be a mapping so we can carry _meta.
+  module Format
     class Yaml < Base
       def self.parse(raw, path: nil)
         raw = raw.dup.force_encoding(Encoding::UTF_8)
@@ -23,7 +22,6 @@ module Textus
 
       def self.serialize(meta:, body:, content: nil)
         if content.is_a?(Hash)
-          # Re-inject _meta as the first key so on-disk shape is stable.
           on_disk = meta && !meta.empty? ? { "_meta" => meta }.merge(content) : content
           ::YAML.dump(on_disk).sub(/\A---\n/, "")
         elsif body && !body.to_s.empty?
@@ -59,7 +57,6 @@ module Textus
         end
       end
 
-      # Mutating filesystem op; returns true if a write happened.
       def self.rewrite_name(path, basename) # rubocop:disable Naming/PredicateMethod
         raw = File.binread(path)
         parsed = parse(raw, path: path)

data/lib/textus/{entry.rb → format.rb}

@@ -1,13 +1,12 @@
 module Textus
-  # Public entry-format dispatcher.
-  module Entry
+  module Format
     SEP = "---".freeze
 
     STRATEGIES = {
-      "markdown" => Markdown,
-      "json" => Json,
-      "yaml" => Yaml,
-      "text" => Text,
+      "markdown" => -> { Format::Markdown },
+      "json" => -> { Format::Json },
+      "yaml" => -> { Format::Yaml },
+      "text" => -> { Format::Text },
     }.freeze
 
     EXT_TO_FORMAT = {
@@ -18,8 +17,8 @@ module Textus
       ".txt" => "text",
     }.freeze
 
-    def self.for_format(format)
-      STRATEGIES.fetch(format.to_s) { raise UsageError.new("unknown entry format: #{format.inspect}") }
+    def self.for(format)
+      STRATEGIES.fetch(format.to_s) { raise Textus::UsageError.new("unknown entry format: #{format.inspect}") }.call
     end
 
     def self.infer_from_extension(ext)
@@ -31,11 +30,11 @@ module Textus
     end
 
     def self.parse(raw, path: nil, format: "markdown")
-      for_format(format).parse(raw, path: path)
+      Format.for(format).parse(raw, path: path)
     end
 
     def self.serialize(meta: {}, body: "", content: nil, format: "markdown")
-      for_format(format).serialize(meta: meta, body: body, content: content)
+      Format.for(format).serialize(meta: meta, body: body, content: content)
     end
   end
 end

data/lib/textus/gate/auth.rb

@@ -4,14 +4,15 @@ module Textus
   class Gate
     class Auth
       FLOOR = {
-        put: %w[lane_writable_by],
-        key_delete: %w[lane_writable_by],
-        key_mv: %w[lane_writable_by],
+        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],
-        key_mv_prefix: %w[lane_writable_by],
-        key_delete_prefix: %w[lane_writable_by],
+        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(
@@ -104,12 +105,15 @@ module Textus
 
       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 "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
@@ -168,6 +172,48 @@ module Textus
         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)

data/lib/textus/gate.rb

@@ -31,6 +31,7 @@ module Textus
       key_mv_prefix: Textus::Command::KeyMvPrefix,
       key_delete_prefix: Textus::Command::KeyDeletePrefix,
       drain: Textus::Command::Drain,
+      ingest: Textus::Command::Ingest,
     }.freeze
 
     ROUTES = {
@@ -62,6 +63,7 @@ module Textus
       Command::KeyMvPrefix => [Textus::Action::KeyMvPrefix],
       Command::KeyDeletePrefix => [Textus::Action::KeyDeletePrefix],
       Command::Drain => [Textus::Action::Drain],
+      Command::Ingest => [Textus::Action::Ingest],
     }.freeze
 
     def initialize(container)

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
@@ -21,9 +21,8 @@ module Textus
         - { 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, 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 →
+        # 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
@@ -32,60 +31,10 @@ module Textus
           format: yaml
           nested: true
           tracked: false
-          kind: produced
-          source:
-            from: fetch
-            handler: machine-intake
-            ttl: 1h # cadence on a long-running server
-            config:
-              machines:
-                local: { via: local }
+          kind: nested
       rules: []
     YAML
 
-    STEPS_README = <<~MD
-      # Steps
-
-      Drop one Ruby file per step. Steps are discovered by convention.
-      Files under `.textus/steps/<kind>/<name>.rb` are loaded at
-      startup and registered.
-
-      ## Conventions
-
-      The directory name (`<kind>`) must be one of:
-      - `fetch`: Acquires data from outside the store.
-      - `transform`: Reshapes projection rows.
-      - `validate`: Validates data before writing.
-      - `observe`: Listens to store events.
-
-      The filename (`<name>.rb`) defines the step name. The class defined
-      in the file must be a subclass of `Textus::Step::<Kind>` (e.g.
-      `Textus::Step::Fetch`) and be wrapped in the `Textus::Step` module.
-
-      ## Example
-
-      ```ruby
-      module Textus
-        module Step
-          class MyFetch < Fetch
-            def call(config:, args:, caps:, **)
-              { content: { "foo" => "bar" } }
-            end
-          end
-        end
-      end
-      ```
-
-      Events: :fetch, :transform, :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(/^/, "  ")
       - { 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 }
@@ -95,12 +44,6 @@ module Textus
         publish:
         - { to: CLAUDE.md, template: orientation.mustache, inject_boot: true }
         - { to: AGENTS.md, template: orientation.mustache, inject_boot: true }
-        source:
-          from: derive
-          select:
-          - knowledge.project
-          - knowledge.runbooks
-          transform: orientation
         kind: produced
     YAML
 
@@ -108,7 +51,6 @@ module Textus
       check_target!(target_root)
       scaffold_dir = File.expand_path("init/templates", __dir__)
       create_directories(target_root)
-      write_steps_readme(target_root, scaffold_dir)
       write_manifest(target_root, with_agent:)
       mcp_status = scaffold_agent(target_root, scaffold_dir, with_agent:)
       setup_state_dirs(target_root)
@@ -120,26 +62,22 @@ module Textus
       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, "steps/fetch"))
-      FileUtils.mkdir_p(File.join(target_root, "steps/transform"))
-      FileUtils.mkdir_p(File.join(target_root, "steps/validate"))
-      FileUtils.mkdir_p(File.join(target_root, "steps/observe"))
+      FileUtils.mkdir_p(File.join(target_root, "workflows"))
       ZONES.each do |z|
         dir = File.join(target_root, "data", z)
         FileUtils.mkdir_p(dir)
         File.write(File.join(dir, ".gitkeep"), "")
       end
-    end
-
-    def self.write_steps_readme(target_root, scaffold_dir)
-      File.write(File.join(target_root, "steps/README.md"), STEPS_README)
-      File.write(
-        File.join(target_root, "steps/fetch/machine-intake.rb"),
-        File.read(File.join(scaffold_dir, "machine_intake.rb")),
-      )
+      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:)
@@ -184,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("steps/transform", "orientation.rb"),
       }.each do |src, dest|
         File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
       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