samagotchi 0.156.0 → 0.158.0

data/lib/samagotchi/session.rb

@@ -10,13 +10,18 @@ require_relative "interrupted_turn"
 require_relative "last_turn"
 require_relative "pending_question"
 require_relative "llm_context_override"
+require_relative "reasoning_history"
+require_relative "thinking"
+require_relative "toolkit"
+require_relative "session_config"
 require_relative "session_setup"
 require_relative "prompt_note"
 require_relative "working_set_pin"
 require_relative "session_review"
+require_relative "session_field"
+require_relative "session_paths"
 require_relative "version"
 
-require_relative "paths"
 require_relative "project_scope"
 require_relative "guardrails/parent_levels"
 
@@ -29,9 +34,11 @@ module Samagotchi
   autoload :ArchiveStore, File.expand_path("archive_store", __dir__)
 
   class Session
+    # The paths and the id rule (SessionPaths): Session.session_dir,
+    # .session_file, .default_state_dir, .valid_id?, .check_id!.
+    extend SessionPaths
+
     METADATA_VERSION = 3
-    STATE_SUBDIR = File.join("samagotchi", "sessions")
-    FILE_EXT = ".json"
 
     STATUS_IDLE = "idle"
     STATUS_RUNNING = "running"
@@ -65,195 +72,323 @@ module Samagotchi
     SORT_KEYS = %w[created_at updated_at].freeze
     SORT_ORDERS = %w[asc desc].freeze
 
-    attr_accessor :id, :metadata_version, :mode, :model_name, :working_directory, :messages,
-                  :created_at, :updated_at, :status, :last_prompt, :first_preview, :test_run,
-                  :used_memory_names
-    # The id the prompt a session is created with gets (SessionManager
-    # .spawn_session), so its first turn is a turn with an id like one sent
-    # later: the worker's first turn takes it as its origin, its reply file
-    # and last_turn carry it, and a wait for it (`chi send --new --wait`,
-    # chi web's create) can name it (`--wait --turn T ID`). nil for a
-    # session created idle, and for one saved before the field existed.
-    attr_accessor :first_turn_id
-    # Memories the session was started with (--memory) and memories hidden
-    # from it (--mute): the worker rebuilds the same prompt on a respawn.
-    # Names as given; the engine normalizes them.
-    attr_accessor :preloaded_memory_names, :muted_memory_names
-    # The name the user gave the session (/title, TitleCommand), else nil:
-    # every list, card and tab shows it in place of #first_preview (see
-    # #display_title). A continue's new link inherits it.
-    attr_accessor :title
-    # The files chi --append-system-prompt put into the session's system
-    # prompt (absolute paths; config.yml's append_system_prompt: entries
-    # aren't stored): kept on respawns, copied by a fork and a continue
-    # (SessionSetup).
-    attr_reader :appended_prompt_files
-
-    def appended_prompt_files=(paths)
-      @appended_prompt_files = Array(paths).map(&:to_s).reject(&:empty?).uniq
+    # A field a session file must have (KeyError without it).
+    REQUIRED = SessionField::REQUIRED
+
+    # How the plain rows read and write their values.
+    BOOLEAN = ->(value) { !!value }
+    NAMES = ->(names) { name_list(names) }
+    LIST = ->(value) { Array(value) }
+    ID = ->(value) { value&.to_s }
+    MESSAGES = ->(messages) { SessionField.scrub_utf8(messages.map { |msg| SessionField.stringify_keys(msg) }) }
+    # A text the user typed or pasted (a prompt, a title): the file gets it
+    # as valid UTF-8 (nil stays nil), the session keeps what it was given.
+    SCRUBBED = ->(value) { SessionField.scrub_utf8(value) }
+    VERDICTS = lambda do |records|
+      records&.map do |record|
+        SessionField.scrub_utf8(record.to_h do |key, entry|
+          [key.to_s, entry.is_a?(Hash) ? SessionField.stringify_keys(entry) : entry]
+        end)
+      end
     end
-    # The model notes the session's system prompt carried at its last build
-    # (Array<PromptNote>: name, scope, chars, digest; ModelNotes), set by the
-    # Engine at each build (a start, a resume's or a woken worker's first
-    # turn, /model) and saved, so what a session ran with can be read later.
-    attr_reader :prompt_notes
-
-    # @param notes [Array<PromptNote, Hash>] a file's hashes are read
-    #   (PromptNote.list)
-    def prompt_notes=(notes)
-      @prompt_notes = PromptNote.list(notes)
+    TOOLKIT_ORIGIN = lambda do |value|
+      origin = value.to_s
+      TOOLKIT_ORIGINS.include?(origin) ? origin : "chosen"
+    end
+    TOOLKIT_ORIGIN_UNREAD = ->(value) { value if value.is_a?(String) && !TOOLKIT_ORIGINS.include?(value) }
+    # The kept value while there is one: the written one is the cast
+    # (never nil), so it can't come first as a level's does.
+    KEPT_FIRST = ->(written, kept) { kept || written }
+    PARENT_ANSWERS = lambda do |value|
+      case (level = Guardrails::ParentPolicy.parse_level(value))
+      when :unset then nil
+      when :invalid then value.to_s.strip
+      else level
+      end
     end
-    # The name model_name was typed as when that differs from the resolved
-    # ref stored in model_name (an alias: `small` for `gemma-small`), else
-    # nil. The models: lookup takes it (HostRegistry#lookup_names).
-    attr_accessor :model_typed
-    # The project the session was started in (ProjectScope.root_for its
-    # folder), stored because worktrees are deleted after a merge and a
-    # deleted folder no longer leads to its repository. nil outside a repo,
-    # and in files written before the field existed (see #project_root).
-    attr_writer :project_root
-    # The session that delegated this one (the `delegate` tool) or that a
-    # plugin forked it from (ctx.sessions.fork), else nil.
-    # Set before the spawn and kept on respawns, like preloaded_memory_names.
-    attr_accessor :parent_id
-    # Started by the `delegate` tool (a fork has a parent_id too, but isn't
-    # one): see #delegate?.
-    attr_writer :delegate
-    # The session this one continues (SessionContinue.run): the
-    # previous link of a chain, "the next run of the same routine", else
-    # nil. Not a parent: archiving one link leaves the next alone. The chain
-    # itself is derived (SessionChain), never stored.
-    attr_accessor :continues
-    # A `chi scratch` session: deleted when its terminal leaves (its worker
-    # deletes it too once its last client is gone), and by the next sweep
-    # (or `chi sessions clean`) when both died first.
-    attr_accessor :scratch
-    # The question this session waits on (PendingQuestion), saved as
-    # session.json's "pending_question"; nil with none. A Hash (a saved
-    # record, string or symbol keys) is read with PendingQuestion.from_file.
-    attr_reader :pending_question
+    private_constant :BOOLEAN, :NAMES, :LIST, :ID, :MESSAGES, :SCRUBBED, :VERDICTS, :TOOLKIT_ORIGIN, :TOOLKIT_ORIGIN_UNREAD, :KEPT_FIRST,
+                     :PARENT_ANSWERS
 
-    def pending_question=(value)
-      @pending_question = PendingQuestion.from_file(value)
-    end
+    # The fields of <id>.json, in the order #save writes them: key => its
+    # SessionField (the value for a file without it, REQUIRED for the ones
+    # it must have; how it is read and written). Session.new, .from_h and
+    # #to_h all go by this table: a new field is one row (plus a
+    # SessionSetup member when a fork and a continue carry it). Messages
+    # change key type on the way (symbols in memory, strings on disk).
+    #
+    # A new field: a chi older than it (from the release after 0.130.0)
+    # keeps the key as it was (#extra_fields) but doesn't honour it, and the
+    # next newer chi reads it again. So it must be safe to come back
+    # unchanged after an older chi ran turns on the session: static data, or
+    # append-only data the older chi never appends to (review, verify_fresh,
+    # first_turn_id, verdicts); a cursor into messages, which an older chi
+    # would have moved, needs a check against what it points at. Only
+    # top-level keys are kept: the value objects (SessionReview,
+    # VerifyFreshOrigin, Toolkit, LastTurn, PendingQuestion, InterruptedTurn,
+    # PromptNote, WorkingSetPin, LLMContextOverride) write their own members
+    # only, so an older chi still drops a new sub-key of one of them; add a
+    # top-level field when an older chi must keep it. A removed key would
+    # stay an extra forever: leave it out of the extras in .from_h then (no
+    # key was ever removed).
+    FIELDS = [
+      SessionField.plain("metadata_version", 1, fresh: METADATA_VERSION),
+      # The chi version that last saved the loaded file (#to_h writes this
+      # chi's VERSION); nil for a file from 0.130.0 or older.
+      SessionField.plain("written_by", nil, write: ->(_) { VERSION }),
+      SessionField.plain("id", REQUIRED),
+      SessionField.plain("mode", REQUIRED),
+      SessionField.plain("model_name", REQUIRED),
+      # The name model_name was typed as when that differs from the resolved
+      # ref stored in model_name (an alias: `small` for `gemma-small`), else
+      # nil. The models: lookup takes it (HostRegistry#lookup_names).
+      SessionField.plain("model_typed", nil),
+      SessionField.plain("working_directory", REQUIRED),
+      # The conversation (symbol keys in memory; .from_h symbolizes a
+      # file's); a running turn's checkpoint is saved in its place (#to_h).
+      SessionField.plain("messages", [], fresh: REQUIRED, write: MESSAGES),
+      SessionField.plain("created_at", REQUIRED),
+      SessionField.plain("updated_at", REQUIRED),
+      SessionField.plain("status", STATUS_IDLE),
+      SessionField.plain("last_prompt", "", write: SCRUBBED),
+      SessionField.plain("first_preview", "", write: SCRUBBED),
+      # The name the user gave the session (/title, TitleCommand), else nil:
+      # every list, card and tab shows it in place of #first_preview (see
+      # #display_title). A continue's new link inherits it.
+      SessionField.plain("title", nil, write: SCRUBBED),
+      SessionField.plain("test_run", false, cast: BOOLEAN, write: BOOLEAN),
+      # The question this session waits on (PendingQuestion), saved as
+      # session.json's "pending_question"; nil with none. A Hash (a saved
+      # record, string or symbol keys) is read with PendingQuestion.from_file.
+      SessionField.value("pending_question", :from_file, scrub: true) { PendingQuestion },
+      SessionField.plain("used_memory_names", [], cast: NAMES, write: LIST),
+      # The project the session was started in (ProjectScope.root_for its
+      # folder), stored because worktrees are deleted after a merge and a
+      # deleted folder no longer leads to its repository. nil outside a repo,
+      # and in files written before the field existed (see #project_root).
+      SessionField.plain("project_root", nil),
+      # Memories the session was started with (--memory) and memories hidden
+      # from it (--mute): the worker rebuilds the same prompt on a respawn.
+      # Names as given; the engine normalizes them.
+      SessionField.plain("preloaded_memory_names", [], cast: NAMES, write: LIST),
+      SessionField.plain("muted_memory_names", [], cast: NAMES, write: LIST),
+      # The model notes the session's system prompt carried at its last build
+      # (Array<PromptNote>: name, scope, chars, digest; ModelNotes), set by the
+      # Engine at each build (a start, a resume's or a woken worker's first
+      # turn, /model) and saved, so what a session ran with can be read later.
+      SessionField.list("prompt_notes") { PromptNote },
+      # The session that delegated this one (the `delegate` tool) or that a
+      # plugin forked it from (ctx.sessions.fork), else nil.
+      # Set before the spawn and kept on respawns, like preloaded_memory_names.
+      SessionField.plain("parent_id", nil, cast: ID),
+      # A `chi scratch` session: deleted when its terminal leaves (its worker
+      # deletes it too once its last client is gone), and by the next sweep
+      # (or `chi sessions clean`) when both died first.
+      SessionField.plain("scratch", false, cast: BOOLEAN),
+      # How the last turn ended (LastTurn), for a parent's wait (ReplyWait)
+      # and the web's notifications (the hub sends it in the summary); nil
+      # before the first turn.
+      SessionField.value("last_turn", :from_file) { LastTurn },
+      # Verdict cards recorded by completed Verify turns, in append order.
+      # A missing field stays missing until the first verdict is recorded
+      # (#verdicts reads it as []). Cast on every set too.
+      SessionField.plain("verdicts", nil, cast: ->(values) { values.nil? ? nil : Array(values) }, write: VERDICTS,
+                                          optional: true),
+      # Started by the `delegate` tool (a fork has a parent_id too, but isn't
+      # one): see #delegate?.
+      SessionField.plain("delegate", false, cast: BOOLEAN),
+      # The session's own llm_context values (LLMContextOverride: strategy,
+      # apply rule, budget), before the model's; nil when it has none (an
+      # empty one is none). Saved, so a --resume and a respawned worker keep
+      # them; a plugin's fork copies them, a delegate child starts without.
+      # A file's parts it can't read are kept (LLMContextOverride.unread).
+      SessionField.level("llm_context", merge_unread: true) { LLMContextOverride },
+      # The session this one continues (SessionContinue.run): the
+      # previous link of a chain, "the next run of the same routine", else
+      # nil. Not a parent: archiving one link leaves the next alone. The chain
+      # itself is derived (SessionChain), never stored.
+      SessionField.plain("continues", nil, cast: ID),
+      # The session's own thinking level (:off, :low, :medium, :high), before
+      # the process default and the model's (Thinking.resolve); nil when it
+      # has none. Saved, so a --resume, a respawned worker and a continue keep
+      # it; a plugin's fork copies it, a delegate child starts without.
+      SessionField.level("thinking", unset: Thinking::DEFAULT.to_s) { Thinking },
+      # The session's own reasoning_history level (:drop, :turn, :all), before
+      # SAMAGOTCHI_REASONING_HISTORY and the model's (ReasoningHistory.resolve);
+      # nil when it has none. Saved and carried like thinking.
+      SessionField.level("reasoning_history", unset: ReasoningHistory::UNSET) { ReasoningHistory },
+      # The files chi --append-system-prompt put into the session's system
+      # prompt (absolute paths; config.yml's append_system_prompt: entries
+      # aren't stored): kept on respawns, copied by a fork and a continue
+      # (SessionSetup). Cast on every set too.
+      SessionField.plain("appended_prompt_files", [], cast: ->(paths) { Array(paths).map(&:to_s).reject(&:empty?).uniq },
+                                                      write: LIST),
+      # The session's toolkit (Toolkit: the tools its prompts declare), as
+      # given when it was created; nil for a session from before toolkits,
+      # which is on Toolkit::FULL (Toolkit.of). Saved and never resolved
+      # again from config, so a respawned worker declares the same tools; a
+      # continue and a fork copy it (SessionSetup.of), a delegate child gets
+      # the one its delegate call named, else toolkit.child
+      # (SessionManager.spawn_session). A Hash or a String reads too.
+      SessionField.value("toolkit", :from_file) { Toolkit },
+      # Why this session is on its toolkit (TOOLKIT_ORIGINS; anything else
+      # reads as chosen). Files from before the field read as chosen, so an
+      # old default session is never newly suggested. Cast on every set too.
+      # An unknown String (a newer chi's origin) is written back as it was
+      # (the Unread rule), until the session sets its own: the kept value
+      # wins over the cast chosen.
+      SessionField.plain("toolkit_origin", "chosen", cast: TOOLKIT_ORIGIN, unread: TOOLKIT_ORIGIN_UNREAD,
+                                                     keep: KEPT_FIRST),
+      # The two parts of #settings (Session.new's settings:, .from_h composes
+      # them): its bundles part, then its core part.
+      SessionField.file_only("bundle_settings", {}, from: :settings, write: ->(settings) { settings.bundles }),
+      SessionField.file_only("config_settings", {}, from: :settings, write: ->(settings) { settings.core }),
+      # The mark of a turn a worker checkpointed and never finished
+      # (InterruptedTurn), as loaded; the next worker settles it and sets it
+      # to nil. While a turn runs, #turn_checkpoint's marker is saved instead.
+      SessionField.value("interrupted_turn", :from_file) { InterruptedTurn },
+      # The session's own guardrails.parent_answers (hard|standard|soft), nil
+      # for none (config.yml's). It may only tighten config.yml's
+      # (Guardrails::ParentPolicy.effective); only the user loosens it
+      # (/parent-answers in a UI). Given at creation (chi --parent-answers,
+      # chi send --new --parent-answers); a respawn, a continue and a fork keep
+      # it (SessionSetup.of), a delegate child takes its parent's. Read as
+      # Guardrails::ParentPolicy.parse_level on every set: a level, or nil for
+      # none ("", "default"); a value that isn't a level is kept as written,
+      # stripped (read as hard: ParentPolicy.session_level).
+      SessionField.plain("parent_answers", nil, cast: PARENT_ANSWERS),
+      # The working set's items the user pinned (/working-set pin;
+      # WorkingSetPin), [] with none: the model's forget_outputs refuses
+      # their outputs. A respawn, a continue and a fork keep them
+      # (SessionSetup.of); a delegate child starts without.
+      SessionField.list("working_set_pins") { WorkingSetPin },
+      # A review session's subjects and source (SessionReview), nil for any
+      # other session.
+      SessionField.value("review", :of, optional: true) { SessionReview },
+      # The id the prompt a session is created with gets (SessionManager
+      # .spawn_session), so its first turn is a turn with an id like one sent
+      # later: the worker's first turn takes it as its origin, its reply file
+      # and last_turn carry it, and a wait for it (`chi send --new --wait`,
+      # chi web's create) can name it (`--wait --turn T ID`). nil for a
+      # session created idle, and for one saved before the field existed.
+      SessionField.plain("first_turn_id", nil, optional: true),
+      # A Verify fresh child's requester, rules and claim (VerifyFreshOrigin),
+      # nil for any other session. Set once, at spawn (VerifyFresh.start).
+      # Autoloaded on the first one (the bundle test kit's load budget).
+      SessionField.value("verify_fresh", :of, optional: true) { VerifyFreshOrigin }
+    ].to_h { |field| [field.key, field] }.freeze
 
-    # How the last turn ended (LastTurn), for a parent's wait (ReplyWait)
-    # and the web's notifications (the hub sends it in the summary); nil
-    # before the first turn.
-    attr_reader :last_turn
+    # FIELDS a session file has only when set: a session without them saves
+    # as it did before they existed.
+    OPTIONAL_FIELDS = FIELDS.values.select(&:optional).map(&:key).freeze
 
-    # @param value [LastTurn, Hash, nil] a file's Hash is read
-    #   (LastTurn.from_file)
-    def last_turn=(value)
-      @last_turn = LastTurn.from_file(value)
+    # Session.new's keywords: every FIELDS row's attr.
+    ATTRS = FIELDS.values.filter_map(&:attr).freeze
+
+    # The plain fields' readers and writers (each one's meaning is at its
+    # FIELDS row): a writer takes the value as given (Session.new and
+    # .from_h cast it), except the ones defined below.
+    attr_accessor :id, :metadata_version, :mode, :model_name, :model_typed, :working_directory, :messages,
+                  :created_at, :updated_at, :status, :last_prompt, :first_preview, :title, :test_run,
+                  :used_memory_names, :preloaded_memory_names, :muted_memory_names, :parent_id, :scratch,
+                  :continues, :first_turn_id
+    attr_writer :project_root, :delegate
+    attr_reader :appended_prompt_files, :written_by
+
+    def appended_prompt_files=(value)
+      @appended_prompt_files = load_field("appended_prompt_files", value)
     end
 
-    # Verdict cards recorded by completed Verify turns, in append order.
-    # A missing field stays missing until the first verdict is recorded.
-    def verdicts = @verdicts || []
+    # The value objects' readers and writers: a writer reads its value as
+    # its FIELDS row does (a file's Hash, the object itself; nil is none).
+    attr_reader :prompt_notes, :pending_question, :last_turn, :interrupted_turn, :toolkit, :review, :verify_fresh,
+                :working_set_pins
 
-    def verdicts=(values)
-      @verdicts = values.nil? ? nil : Array(values)
+    def prompt_notes=(value)
+      @prompt_notes = load_field("prompt_notes", value)
     end
 
-    # The mark of a turn a worker checkpointed and never finished
-    # (InterruptedTurn), as loaded; the next worker settles it and sets it
-    # to nil. While a turn runs, #turn_checkpoint's marker is saved instead.
-    attr_reader :interrupted_turn
+    def pending_question=(value)
+      @pending_question = load_field("pending_question", value)
+    end
 
-    # @param value [InterruptedTurn, Hash, nil]
-    def interrupted_turn=(value)
-      @interrupted_turn = InterruptedTurn.from_file(value)
+    def last_turn=(value)
+      @last_turn = load_field("last_turn", value)
     end
 
-    # The running turn's checkpoint (TurnCheckpoint): {messages:, marker:}
-    # (marker an InterruptedTurn). While +status+ is running, every save
-    # writes these messages and the marker instead of #messages and
-    # #interrupted_turn, so a save in the middle of the turn (a question
-    # asked, the checkpoint's own) keeps the turn so far on disk; #messages
-    # itself is never touched. The turn's end sets status idle before it
-    # saves, so that save writes the real messages, without a marker. Not
-    # saved; the worker clears it after each turn.
-    attr_accessor :turn_checkpoint
-    # The session's own llm_context values (LLMContextOverride: strategy,
-    # apply rule, budget), before the model's; nil when it has none.
-    # Saved, so a --resume and a respawned worker keep them; a plugin's
-    # fork copies them, a delegate child starts without.
-    attr_reader :llm_context
-
-    # @param value [LLMContextOverride, Hash, nil] an empty one is nil; a
-    #   file's Hash keeps the fields it can't read (LLMContextOverride.unread),
-    #   saved back as they were until the session sets its own
-    def llm_context=(value)
-      @llm_context_unread = LLMContextOverride.unread(value)
-      @llm_context = LLMContextOverride.from_file(value)
+    def interrupted_turn=(value)
+      @interrupted_turn = load_field("interrupted_turn", value)
     end
 
-    # The session file's "llm_context": the override's fields over the ones
-    # it couldn't read; nil when there are none.
-    def llm_context_file
-      saved = @llm_context_unread.merge(@llm_context&.to_file || {})
-      saved.empty? ? nil : saved
+    def toolkit=(value)
+      @toolkit = load_field("toolkit", value)
     end
 
-    # The session's own thinking level (:off, :low, :medium, :high), before
-    # the process default and the model's (Thinking.resolve); nil when it
-    # has none. Saved, so a --resume, a respawned worker and a continue keep
-    # it; a plugin's fork copies it, a delegate child starts without.
-    attr_reader :thinking
+    def review=(value)
+      @review = load_field("review", value)
+    end
 
-    # @param value [Symbol, String, nil] a value that isn't a level reads
-    #   as nil and is saved back as written, until the session sets its own
-    def thinking=(value)
-      @thinking = Thinking.session_level(value)
-      unread = @thinking.nil? && value.is_a?(String) && !value.strip.casecmp?(Thinking::DEFAULT.to_s)
-      @thinking_unread = unread ? value : nil
+    def verify_fresh=(value)
+      @verify_fresh = load_field("verify_fresh", value)
     end
 
-    # The session file's "thinking": the level, else a value it couldn't
-    # read; nil when there is neither.
-    def thinking_file = @thinking&.to_s || @thinking_unread
+    def working_set_pins=(value)
+      @working_set_pins = load_field("working_set_pins", value)
+    end
 
-    # The session's own reasoning_history level (:drop, :turn, :all), before
-    # SAMAGOTCHI_REASONING_HISTORY and the model's (ReasoningHistory.resolve);
-    # nil when it has none. Saved and carried like #thinking.
-    attr_reader :reasoning_history
+    # Verdict cards recorded by completed Verify turns ([] before the
+    # first; the file has none then).
+    def verdicts = @verdicts || []
 
-    # @param value [Symbol, String, nil] a value that isn't a level reads
-    #   as nil and is saved back as written, until the session sets its own
-    def reasoning_history=(value)
-      @reasoning_history = ReasoningHistory.session_level(value)
-      unread = @reasoning_history.nil? && value.is_a?(String) && !value.strip.casecmp?(ReasoningHistory::UNSET)
-      @reasoning_history_unread = unread ? value : nil
+    def verdicts=(value)
+      @verdicts = load_field("verdicts", value)
     end
 
-    # The session file's "reasoning_history": the level, else a value it
-    # couldn't read; nil when there is neither.
-    def reasoning_history_file = @reasoning_history&.to_s || @reasoning_history_unread
+    # The session's own levels' and setup's readers and writers: a writer
+    # reads its value as its FIELDS row does; thinking, reasoning_history
+    # and llm_context keep what of it they couldn't read (SessionField.level).
+    attr_reader :llm_context, :thinking, :reasoning_history, :toolkit_origin, :parent_answers
 
-    # The session's toolkit (Toolkit: the tools its prompts declare), as
-    # given when it was created; nil for a session from before toolkits,
-    # which is on Toolkit::FULL (Toolkit.of). Saved and never resolved
-    # again from config, so a respawned worker declares the same tools; a
-    # continue and a fork copy it (SessionSetup.of), a delegate child gets
-    # the one its delegate call named, else toolkit.child
-    # (SessionManager.spawn_session).
-    attr_reader :toolkit
+    def llm_context=(value)
+      @llm_context = load_field("llm_context", value)
+    end
 
-    # @param value [Toolkit, Hash, String, nil] the session file's form too
-    def toolkit=(value)
-      @toolkit = value.is_a?(Toolkit) ? value : Toolkit.from_file(value)
+    def thinking=(value)
+      @thinking = load_field("thinking", value)
     end
 
-    # Why this session is on its toolkit. Files from before the field read
-    # as chosen, so an old default session is never newly suggested.
-    attr_reader :toolkit_origin
+    def reasoning_history=(value)
+      @reasoning_history = load_field("reasoning_history", value)
+    end
 
     def toolkit_origin=(value)
-      origin = value.to_s
-      @toolkit_origin = TOOLKIT_ORIGINS.include?(origin) ? origin : "chosen"
+      @toolkit_origin = load_field("toolkit_origin", value)
+    end
+
+    # The user chose the toolkit (/toolkit, the toolkit binding's use): the
+    # origin is chosen. Whether that changes what the file holds, so the
+    # caller saves only then: a kept unknown origin (the Unread rule) reads
+    # as chosen but is written as it was, so it counts as a change.
+    # @return [Boolean]
+    def choose_toolkit_origin!
+      field = FIELDS.fetch("toolkit_origin")
+      was = field.dump(@toolkit_origin, @unread["toolkit_origin"])
+      self.toolkit_origin = "chosen"
+      was != field.dump(@toolkit_origin, @unread["toolkit_origin"])
+    end
+
+    def parent_answers=(value)
+      @parent_answers = load_field("parent_answers", value)
     end
 
+    # The running turn's checkpoint (TurnCheckpoint): {messages:, marker:}
+    # (marker an InterruptedTurn). While +status+ is running, every save
+    # writes these messages and the marker instead of #messages and
+    # #interrupted_turn, so a save in the middle of the turn (a question
+    # asked, the checkpoint's own) keeps the turn so far on disk; #messages
+    # itself is never touched. The turn's end sets status idle before it
+    # saves, so that save writes the real messages, without a marker. Not
+    # saved; the worker clears it after each turn.
+    attr_accessor :turn_checkpoint
     # The session's own settings (chi --set), a SessionConfig::Settings:
     # empty for none and for a session from before them. Its core part
     # ({key => value}: recap.enabled) is the file's config_settings, its
@@ -269,48 +404,9 @@ module Samagotchi
       @settings = SessionConfig::Settings.of(value)
     end
 
-    # The session's own guardrails.parent_answers (hard|standard|soft), nil
-    # for none (config.yml's). It may only tighten config.yml's
-    # (Guardrails::ParentPolicy.effective); only the user loosens it
-    # (/parent-answers in a UI). Given at creation (chi --parent-answers,
-    # chi send --new --parent-answers); a respawn, a continue and a fork keep
-    # it (SessionSetup.of), a delegate child takes its parent's.
-    attr_reader :parent_answers
-
-    # @param value [String, Symbol, nil] read as
-    #   Guardrails::ParentPolicy.parse_level: a level, or nil for none ("",
-    #   "default"); a value that isn't a level is kept as written, stripped
-    #   (read as hard: ParentPolicy.session_level)
-    def parent_answers=(value)
-      level = Guardrails::ParentPolicy.parse_level(value)
-      @parent_answers = case level
-                        when :unset then nil
-                        when :invalid then value.to_s.strip
-                        else level
-                        end
-    end
-
-    # A review session's subjects and source (SessionReview), nil for any
-    # other session.
-    attr_reader :review
-
-    # @param value [SessionReview, Hash, nil] the session file's form too
-    def review=(value)
-      @review = SessionReview.of(value)
-    end
-
     # Whether this is a review session (chi review, the web's Start review).
     def review? = !@review.nil?
 
-    # A Verify fresh child's requester, rules and claim (VerifyFreshOrigin),
-    # nil for any other session. Set once, at spawn (VerifyFresh.start).
-    attr_reader :verify_fresh
-
-    # @param value [VerifyFreshOrigin, Hash, nil] the session file's form too
-    def verify_fresh=(value)
-      @verify_fresh = value.nil? ? nil : VerifyFreshOrigin.of(value)
-    end
-
     # The session whose participants.json names this session's
     # participants: a Verify fresh child's parent (its requester's grant is
     # the parent's), else the session itself.
@@ -323,17 +419,6 @@ module Samagotchi
 
     TOOL_ROLES = %w[tool_response tool].freeze
 
-    # The working set's items the user pinned (/working-set pin;
-    # WorkingSetPin), [] with none: the model's forget_outputs refuses
-    # their outputs. A respawn, a continue and a fork keep them
-    # (SessionSetup.of); a delegate child starts without.
-    attr_reader :working_set_pins
-
-    # @param value [Array<WorkingSetPin, Hash>] the session file's form too
-    def working_set_pins=(value)
-      @working_set_pins = WorkingSetPin.list(value)
-    end
-
     # The hook that stopped the last turn (stop_turn, or a cut with no retry
     # left), e.g. "loop-guard"; nil when it ended otherwise.
     def stopped_by
@@ -370,59 +455,18 @@ module Samagotchi
     # FIELDS as they were. Never read by this chi.
     attr_reader :extra_fields
 
-    # The chi version that last saved the loaded file (#to_h writes this
-    # chi's VERSION); nil for a file from 0.130.0 or older.
-    attr_reader :written_by
-
-    def initialize(id:, mode:, model_name:, working_directory:, messages:, created_at:, updated_at:,
-                   metadata_version: METADATA_VERSION, written_by: nil, status: STATUS_IDLE, last_prompt: "",
-                   first_preview: "", first_turn_id: nil, test_run: false, pending_question: nil,
-                   used_memory_names: [], project_root: nil,
-                   preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
-                   last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
-                   continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
-                   toolkit: nil, toolkit_origin: "chosen", settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
-                   working_set_pins: [], review: nil, verdicts: nil, verify_fresh: nil, extra_fields: {})
-      @id = id
-      @metadata_version = metadata_version
-      @written_by = written_by
-      @mode = mode
-      @model_name = model_name
-      @model_typed = model_typed
-      @working_directory = working_directory
-      @messages = messages
-      @created_at = created_at
-      @updated_at = updated_at
-      @status = status
-      @last_prompt = last_prompt
-      @first_preview = first_preview
-      @first_turn_id = first_turn_id
-      @title = title
-      @test_run = !!test_run
-      self.pending_question = pending_question
-      @used_memory_names = self.class.name_list(used_memory_names)
-      @preloaded_memory_names = self.class.name_list(preloaded_memory_names)
-      @muted_memory_names = self.class.name_list(muted_memory_names)
-      self.prompt_notes = prompt_notes
-      @project_root = project_root
-      @parent_id = parent_id&.to_s
-      @scratch = !!scratch
-      self.last_turn = last_turn
-      @delegate = !!delegate
-      @continues = continues&.to_s
-      self.llm_context = llm_context
-      self.thinking = thinking
-      self.reasoning_history = reasoning_history
-      self.appended_prompt_files = appended_prompt_files
-      self.toolkit = toolkit
-      self.toolkit_origin = toolkit_origin
+    # Every FIELDS row's attr is a keyword (a missing required one or an
+    # unknown one raises ArgumentError, as Ruby's keywords do), given as is
+    # (cast by its row, as the writers cast); +settings+ is the
+    # settings pair's one value, +extra_fields+ the file's unknown keys.
+    def initialize(extra_fields: {}, settings: nil, **attrs)
+      check_attrs!(attrs)
+      # What the level fields couldn't read, by key (SessionField.level).
+      @unread = {}
+      FIELDS.each_value do |field|
+        instance_variable_set(field.ivar, load_field(field.key, attrs.fetch(field.attr) { field.fresh_value })) if field.attr
+      end
       self.settings = settings
-      self.parent_answers = parent_answers
-      self.working_set_pins = working_set_pins
-      self.review = review
-      self.verdicts = verdicts
-      self.verify_fresh = verify_fresh
-      self.interrupted_turn = interrupted_turn
       @extra_fields = extra_fields.to_h { |key, value| [key.to_s, value] }.freeze
       @turn_checkpoint = nil
       @archived = false
@@ -515,16 +559,20 @@ module Samagotchi
     # Build a new, unsaved session.
     # @param messages [Array<Hash>] a conversation to start from (a fork's
     #   seed); [] by default
-    # @param setup [SessionSetup] the session's own settings (none by default)
+    # @param setup [SessionSetup, nil] the session's own settings (none by
+    #   default): each member is the field of the same name (a member that
+    #   isn't one is an ArgumentError), a toolkit_origin of none is chosen
     # @param now [Time] its created_at and updated_at (a spec's clock)
     # @raise [Toolkit::Refused] its toolkit (setup's, else the configured
     #   one SessionManager.spawn_session gives it) builds on a config kit
     #   with an invalid groups: (Toolkit.check_new!)
     def self.new_session(mode:, model_name:, working_directory:, test_run: nil,
                          preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, messages: [],
-                         scratch: false, model_typed: nil, delegate: false, setup: SessionSetup.new, continues: nil,
+                         scratch: false, model_typed: nil, delegate: false, setup: nil, continues: nil,
                          review: nil, now: Time.now)
-      Toolkit.check_new!(setup.toolkit || Toolkit.configured(delegate: delegate))
+      own = setup.to_h
+      own = own.merge(toolkit_origin: own[:toolkit_origin] || "chosen")
+      Toolkit.check_new!(own[:toolkit] || Toolkit.configured(delegate: delegate))
       now = now.iso8601(3)
       resolved_test = if test_run.nil?
                         test_session_env?
@@ -549,17 +597,9 @@ module Samagotchi
         parent_id: parent_id,
         scratch: scratch,
         delegate: delegate,
-        llm_context: setup.llm_context,
-        thinking: setup.thinking,
-        reasoning_history: setup.reasoning_history,
-        appended_prompt_files: setup.appended_prompt_files,
-        toolkit: setup.toolkit,
-        toolkit_origin: setup.toolkit_origin || "chosen",
-        settings: setup.settings,
-        parent_answers: setup.parent_answers,
-        working_set_pins: setup.working_set_pins,
         continues: continues,
-        review: review
+        review: review,
+        **own
       )
     end
 
@@ -588,84 +628,12 @@ module Samagotchi
       raise ArgumentError, "Session file corrupted (#{session_id}): #{e.message}"
     end
 
-    # A field a session file must have (KeyError without it).
-    REQUIRED = Object.new.freeze
-
-    # The fields of <id>.json, in the order #save writes them: key => the
-    # value for a file without it (REQUIRED for the ones it must have).
-    # .from_h and #to_h both go by this table; messages change key type on
-    # the way (symbols in memory, strings on disk); last_turn, prompt_notes
-    # and pending_question are value objects in memory (LastTurn,
-    # PromptNote, PendingQuestion).
-    #
-    # A new field: a chi older than it (from the release after 0.130.0)
-    # keeps the key as it was (#extra_fields) but doesn't honour it, and the
-    # next newer chi reads it again. So it must be safe to come back
-    # unchanged after an older chi ran turns on the session: static data, or
-    # append-only data the older chi never appends to (review, verify_fresh,
-    # first_turn_id, verdicts); a cursor into messages, which an older chi
-    # would have moved, needs a check against what it points at. Only
-    # top-level keys are kept: the value objects (SessionReview,
-    # VerifyFreshOrigin, Toolkit, LastTurn, PendingQuestion, InterruptedTurn,
-    # PromptNote, WorkingSetPin, LLMContextOverride) write their own members
-    # only, so an older chi still drops a new sub-key of one of them; add a
-    # top-level field when an older chi must keep it. A removed key would
-    # stay an extra forever: leave it out of the extras in .from_h then (no
-    # key was ever removed).
-    FIELDS = {
-      "metadata_version" => 1,
-      "written_by" => nil,
-      "id" => REQUIRED,
-      "mode" => REQUIRED,
-      "model_name" => REQUIRED,
-      "model_typed" => nil,
-      "working_directory" => REQUIRED,
-      "messages" => [],
-      "created_at" => REQUIRED,
-      "updated_at" => REQUIRED,
-      "status" => STATUS_IDLE,
-      "last_prompt" => "",
-      "first_preview" => "",
-      "title" => nil,
-      "test_run" => false,
-      "pending_question" => nil,
-      "used_memory_names" => [],
-      "project_root" => nil,
-      "preloaded_memory_names" => [],
-      "muted_memory_names" => [],
-      "prompt_notes" => [],
-      "parent_id" => nil,
-      "scratch" => false,
-      "last_turn" => nil,
-      "verdicts" => nil,
-      "delegate" => false,
-      "llm_context" => nil,
-      "continues" => nil,
-      "thinking" => nil,
-      "reasoning_history" => nil,
-      "appended_prompt_files" => [],
-      "toolkit" => nil,
-      "toolkit_origin" => "chosen",
-      "bundle_settings" => {},
-      "config_settings" => {},
-      "interrupted_turn" => nil,
-      "parent_answers" => nil,
-      "working_set_pins" => [],
-      "review" => nil,
-      "first_turn_id" => nil,
-      "verify_fresh" => nil
-    }.freeze
-
-    # FIELDS a session file has only when set: a session without them saves
-    # as it did before they existed.
-    OPTIONAL_FIELDS = %w[review first_turn_id verdicts verify_fresh].freeze
-
     # A session from a parsed session file. +messages+ false leaves the
     # conversation out (the lists' lightweight summaries).
     # @raise [KeyError] for a missing REQUIRED field
     def self.from_h(data, messages: true)
-      attrs = FIELDS.to_h do |key, default|
-        [key.to_sym, default.equal?(REQUIRED) ? data.fetch(key) : data.fetch(key, default)]
+      attrs = FIELDS.to_h do |key, field|
+        [key.to_sym, field.required? ? data.fetch(key) : data.fetch(key, field.default)]
       end
       attrs[:settings] = SessionConfig::Settings.new(core: attrs.delete(:config_settings), bundles: attrs.delete(:bundle_settings))
       attrs[:messages] = messages ? Array(attrs[:messages]).map { |msg| symbolize_message_keys(msg) } : []
@@ -717,7 +685,8 @@ module Samagotchi
       id = id_or_prefix.to_s
       return id unless valid_id?(id) && !File.exist?(session_path(id, state_dir: state_dir))
 
-      matches = Dir.glob(File.join(state_dir, "#{id}*#{FILE_EXT}")).map { |path| File.basename(path, FILE_EXT) }.sort
+      matches = Dir.glob(File.join(state_dir, "#{id}*#{SessionPaths::FILE_EXT}"))
+                    .map { |path| File.basename(path, SessionPaths::FILE_EXT) }.sort
       return matches.fetch(0, id) if matches.size <= 1
 
       lines = matches.map do |match|
@@ -743,7 +712,7 @@ module Samagotchi
       sort_key = SORT_KEYS.include?(sort.to_s) ? sort.to_s : "updated_at"
       sort_order = SORT_ORDERS.include?(order.to_s) ? order.to_s : "desc"
 
-      sessions = Dir.glob(File.join(state_dir, "*#{FILE_EXT}")).filter_map { |path| summary_from_file(path) }
+      sessions = Dir.glob(File.join(state_dir, "*#{SessionPaths::FILE_EXT}")).filter_map { |path| summary_from_file(path) }
       sessions.each { |s| s.archived = ArchiveStore.archived?(session_dir(s.id, state_dir: state_dir)) }
       sessions.reject!(&:archived) unless include_archived
       if project_root
@@ -823,40 +792,35 @@ module Samagotchi
     # messages.
     def to_h
       checkpoint = checkpointed
-      FIELDS.keys.to_h do |key|
-        value = case key
-                when "messages"
-                  (checkpoint ? checkpoint[:messages] : @messages).map { |msg| scrub_utf8(stringify_message_keys(msg)) }
-                when "interrupted_turn" then (checkpoint ? checkpoint[:marker] : @interrupted_turn)&.to_file
-                when "pending_question" then @pending_question && scrub_utf8(@pending_question.to_file)
-                when "written_by" then VERSION
-                when "test_run" then !!@test_run
-                when "delegate" then @delegate
-                when "llm_context" then llm_context_file
-                when "thinking" then thinking_file
-                when "reasoning_history" then reasoning_history_file
-                when "toolkit" then @toolkit&.to_file
-                when "bundle_settings" then @settings.bundles
-                when "config_settings" then @settings.core
-                when "prompt_notes" then @prompt_notes.map(&:to_file)
-                when "last_turn" then @last_turn&.to_file
-                when "working_set_pins" then @working_set_pins.map(&:to_file)
-                when "review" then @review&.to_file
-                when "verify_fresh" then @verify_fresh&.to_file
-                when "verdicts"
-                  @verdicts&.map do |record|
-                    scrub_utf8(record.to_h do |key, entry|
-                      [key.to_s, entry.is_a?(Hash) ? stringify_message_keys(entry) : entry]
-                    end)
-                  end
-                when "used_memory_names", "preloaded_memory_names", "muted_memory_names", "appended_prompt_files"
-                  Array(instance_variable_get(:"@#{key}"))
-                else instance_variable_get(:"@#{key}")
+      FIELDS.each_value.with_object({}) do |field, file|
+        value = case field.key
+                when "messages" then field.dump(checkpoint ? checkpoint[:messages] : @messages)
+                when "interrupted_turn" then field.dump(checkpoint ? checkpoint[:marker] : @interrupted_turn)
+                else field.dump(instance_variable_get(field.ivar), @unread[field.key])
                 end
-        [key, value]
-      end.reject { |key, value| value.nil? && OPTIONAL_FIELDS.include?(key) }
-        .merge(@extra_fields.reject { |key, _| FIELDS.key?(key) })
+        file[field.key] = value unless value.nil? && field.optional
+      end.merge(@extra_fields.reject { |key, _| FIELDS.key?(key) })
+    end
+
+    # +value+ as +key+'s FIELDS row reads it (its writer's value); what of
+    # it a level field couldn't read is kept for #to_h.
+    def load_field(key, value)
+      field = FIELDS.fetch(key)
+      @unread[key] = field.unread.call(value) if field.unread
+      field.cast_value(value)
+    end
+    private :load_field
+
+    # @raise [ArgumentError] a keyword Session.new doesn't take, or a
+    #   required one missing (Ruby's own wording)
+    def check_attrs!(attrs)
+      unknown = attrs.keys - ATTRS
+      raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
+
+      missing = FIELDS.values.select(&:fresh_required?).map(&:attr) - attrs.keys
+      raise ArgumentError, "missing keyword#{"s" if missing.size > 1}: #{missing.map(&:inspect).join(", ")}" unless missing.empty?
     end
+    private :check_attrs!
 
     # The running turn's checkpoint, while the turn runs (#turn_checkpoint).
     def checkpointed
@@ -916,45 +880,6 @@ module Samagotchi
       nil
     end
 
-    # An id that is not a session id: it could name a path outside the
-    # sessions dir ("../x", "/etc", "a/b", a NUL), or is empty.
-    class InvalidId < ArgumentError; end
-
-    # Ids are SecureRandom.uuid; anything made of letters, digits, "-" and
-    # "_" (up to 128, not starting with "-") is taken, so a UUID prefix the
-    # CLI resolves passes too. This is the one check every id from outside
-    # (the bridge, the web routes, chi send/note, delegate) meets before it
-    # becomes a path: session_dir and the session file path refuse others.
-    VALID_ID = /\A[A-Za-z0-9_][A-Za-z0-9_-]{0,127}\z/
-
-    def self.valid_id?(session_id)
-      session_id.is_a?(String) && VALID_ID.match?(session_id)
-    end
-
-    # @raise [InvalidId] unless valid_id?(session_id)
-    def self.check_id!(session_id)
-      return session_id if valid_id?(session_id)
-
-      raise InvalidId, "invalid session id: #{session_id.to_s[0, 80].inspect}"
-    end
-
-    # Directory for a specific session (holds IPC files alongside session.json).
-    # @raise [InvalidId] for an id that isn't one (valid_id?)
-    def self.session_dir(session_id, state_dir: default_state_dir)
-      File.join(state_dir, check_id!(session_id))
-    end
-
-    # A session's <id>.json.
-    # @raise [InvalidId] for an id that isn't one (valid_id?)
-    def self.session_file(session_id, state_dir: default_state_dir)
-      File.join(state_dir, "#{check_id!(session_id)}#{FILE_EXT}")
-    end
-
-    # XDG-aware sessions directory.
-    def self.default_state_dir(env: ENV)
-      File.join(Paths.state_home(env: env), STATE_SUBDIR)
-    end
-
     # What names the session: its #title when it has one, else its
     # #first_preview.
     def display_title
@@ -984,8 +909,9 @@ module Samagotchi
     # A prompt as a one-line preview: whitespace collapsed, cut at 80 chars.
     # A quoted or annotated message previews by what was typed under the
     # quote; a quote alone by its words, without the "> " markers or label.
+    # Bytes that aren't UTF-8 preview as ?, as the file saves them.
     def self.preview_of(text)
-      norm = preview_words(text.to_s).gsub(/\s+/, " ").strip
+      norm = preview_words(SessionField.scrub_utf8(text.to_s)).gsub(/\s+/, " ").strip
       norm.length > 80 ? "#{norm[0, 80]}…" : norm
     end
 
@@ -1013,24 +939,6 @@ module Samagotchi
       text.empty? ? nil : self.class.preview_of("note: #{text}")
     end
 
-    def stringify_message_keys(hash)
-      hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
-    end
-
-    # The last guard before JSON.generate, which raises on bytes that
-    # aren't UTF-8: a save that raised would lose the whole conversation.
-    # ToolRunner already scrubs tool output; this covers any other source.
-    def scrub_utf8(obj)
-      case obj
-      when String
-        str = obj.encoding == Encoding::UTF_8 ? obj : obj.dup.force_encoding(Encoding::UTF_8)
-        str.valid_encoding? ? str : str.scrub("?")
-      when Array then obj.map { |element| scrub_utf8(element) }
-      when Hash then obj.to_h { |key, value| [key, scrub_utf8(value)] }
-      else obj
-      end
-    end
-
     class << self
       private