textus 0.53.0 → 0.54.1

data/lib/textus/envelope/reader.rb

@@ -0,0 +1,46 @@
+module Textus
+  class Envelope
+    # Read-only counterpart to EnvelopeWriter. Resolves a key, reads the
+    # bytes, parses them via the format strategy, and hands back an
+    # Envelope. Used by Mv (pre-move inspection) and by EnvelopeWriter
+    # (existing-uid lookup for the uid-preservation step in #put).
+    #
+    # No audit, no events, no permission checks — those live one layer up.
+    class Reader
+      def self.from(container:)
+        new(file_store: container.file_store, manifest: container.manifest)
+      end
+
+      def initialize(file_store:, manifest:)
+        @file_store = file_store
+        @manifest   = manifest
+      end
+
+      def read(key)
+        res = @manifest.resolver.resolve(key)
+        path = res.path
+        return nil unless @file_store.exists?(path)
+
+        mentry = res.entry
+        raw = @file_store.read(path)
+        parsed = Format.for(mentry.format).parse(raw, path: path)
+        Textus::Envelope.build(
+          key: key, mentry: mentry, path: path,
+          meta: parsed["_meta"], body: parsed["body"],
+          etag: Etag.for_bytes(raw), content: parsed["content"]
+        )
+      end
+
+      def existing_uid(key)
+        env = read(key)
+        env&.uid
+      rescue StandardError
+        nil
+      end
+
+      def exists?(key)
+        @file_store.exists?(@manifest.resolver.resolve(key).path)
+      end
+    end
+  end
+end

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/envelope.rb

@@ -1,10 +1,23 @@
 # frozen_string_literal: true
 
+require "dry-struct"
+
 module Textus
-  Envelope = Data.define(
-    :protocol, :key, :lane, :owner, :path, :format,
-    :uid, :etag, :schema_ref, :meta, :body, :content, :freshness
-  ) do
+  class Envelope < Dry::Struct
+    attribute :protocol,   Types::String
+    attribute :key,        Types::String
+    attribute :lane,       Types::String
+    attribute :owner,      Types::String.optional
+    attribute :path,       Types::String
+    attribute :format,     Types::FormatName
+    attribute :etag,       Types::String
+    attribute :uid,        Types::String.optional
+    attribute :schema_ref, Types::String.optional
+    attribute :meta,       Types::Hash.default({}.freeze)
+    attribute :body,       Types::String.optional
+    attribute :content,    Types::Any.optional
+    attribute :freshness,  Types::Any.optional
+
     # rubocop:disable Metrics/ParameterLists
     def self.build(key:, mentry:, path:, meta:, body:, etag:, content: nil, freshness: nil)
       # rubocop:enable Metrics/ParameterLists
@@ -30,6 +43,8 @@ module Textus
       v.is_a?(String) ? v : nil
     end
 
+    def with(**attrs) = self.class.new(to_h.merge(attrs))
+
     def to_h_for_wire
       h = {
         "protocol" => protocol,
@@ -49,8 +64,6 @@ module Textus
       h
     end
 
-    alias_method :zone, :lane
-
     def stale?
       return false if freshness.nil?
 

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,11 +205,19 @@ 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(
         "flag_renamed",
-        "#{old_flag} was renamed in textus/3 — use #{new_flag}",
+        "#{old_flag} was renamed in textus/4 — use #{new_flag}",
         details: { "old" => old_flag, "new" => new_flag },
         hint: "Use #{new_flag} instead.",
         exit_code: 2,

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)