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

@@ -2,7 +2,7 @@
 
 module Textus
   Envelope = Data.define(
-    :protocol, :key, :zone, :owner, :path, :format,
+    :protocol, :key, :lane, :owner, :path, :format,
     :uid, :etag, :schema_ref, :meta, :body, :content, :freshness
   ) do
     # rubocop:disable Metrics/ParameterLists
@@ -11,7 +11,7 @@ module Textus
       new(
         protocol: Textus::PROTOCOL,
         key: key,
-        zone: mentry.zone,
+        lane: mentry.lane,
         owner: mentry.owner,
         path: path,
         format: mentry.format,
@@ -34,7 +34,7 @@ module Textus
       h = {
         "protocol" => protocol,
         "key" => key,
-        "zone" => zone,
+        "lane" => lane,
         "owner" => owner,
         "path" => path,
         "format" => format,
@@ -49,6 +49,8 @@ module Textus
       h
     end
 
+    alias_method :zone, :lane
+
     def stale?
       return false if freshness.nil?
 

data/lib/textus/errors.rb

@@ -1,24 +1,32 @@
 module Textus
+  ErrorInfo = Data.define(:details, :exit_code, :hint) do
+    def self.for(details: {}, exit_code: 1, hint: nil)
+      new(details: details, exit_code: exit_code, hint: hint)
+    end
+  end
+
   class Error < StandardError
-    attr_reader :code, :details, :exit_code, :hint
+    attr_reader :code
 
-    def initialize(code, message, details: {}, exit_code: 1, hint: nil)
+    def initialize(code, message, info: nil, details: {}, exit_code: 1, hint: nil)
       super(message)
       @code = code
-      @details = details
-      @exit_code = exit_code
-      @hint = hint
+      @info = info || ErrorInfo.for(details:, exit_code:, hint:)
     end
 
+    def details = @info.details
+    def exit_code = @info.exit_code
+    def hint = @info.hint
+
     def to_envelope
       env = {
         "protocol" => Textus::PROTOCOL,
         "ok" => false,
         "code" => @code,
         "message" => message,
-        "details" => @details,
+        "details" => details,
       }
-      env["hint"] = @hint if @hint
+      env["hint"] = hint if hint
       env
     end
   end
@@ -97,7 +105,7 @@ module Textus
         else
           "no declared role"
         end
-      details = { "key" => k, "zone" => z }
+      details = { "key" => k, "lane" => z }
       details["verb"] = verb if verb
       details["holders"] = holders if holders
       super(
@@ -150,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 =
@@ -177,7 +181,7 @@ module Textus
   class PublishError < Error
     def initialize(m, target: nil)
       hint =
-        ("file at #{target} wasn't published by textus; back it up and delete it, or move it under .textus/zones/" if target)
+        ("file at #{target} wasn't published by textus; back it up and delete it, or move it under .textus/data/" if target)
       super("publish_error", m, details: target ? { "target" => target } : {}, hint: hint)
     end
   end
@@ -201,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