Split OuterBrain persistence store boundary

Author: nshkrdotcom

.blitz/test_state_v1/indexes/task_states.ndjson

@@ -24,6 +24,13 @@ callers keep using ref-only contract records; this package remains the explicit
 raw Ecto/Postgres durable opt-in and is not required for default semantic
 runtime execution.
 
+The OTP application does not read app env to decide whether durable persistence
+is enabled. Hosts that need Postgres durability must supervise
+the persistence Repo child explicitly with their own repo config, or start it
+explicitly in tests with the Docker/container config. The dependency
+application remains inert by default so runtime configuration is not hidden in
+global app env.
+
 ## Persistence Documentation
 
 See `docs/persistence.md` for tiers, defaults, adapters, unsupported selections, config examples, restart claims, durability claims, debug sidecar behavior, redaction guarantees, migration or preflight behavior, and no-bypass scope when applicable.

core/outer_brain_persistence/README.md

@@ -33,6 +33,12 @@ Unsupported adapter selections fail before mutation. Silent fallback from durabl
 
 Configuration is explicit caller data first, package option second, release profile third, and built-in default last. Governed flows do not read process environment, local credential files, provider defaults, singleton clients, or application configuration as authority unless this package names a standalone boot boundary.
 
+## OTP Ownership And Repo Configuration
+
+`OuterBrain.Persistence.Application` is inert by default and does not read app env to start or configure Postgres. Hosts that need durable storage own the supervision decision by starting `OuterBrain.Persistence.Repo` with explicit config in their own supervision tree. Tests may start the repo directly with container-derived config.
+
+This keeps durability opt-in visible at the caller boundary: no code path can silently enable Postgres persistence through global app configuration, and `OuterBrain.Persistence.Repo` receives the config that its caller supplied.
+
 ## Example Config
 
 ```elixir

core/outer_brain_persistence/docs/persistence.md

@@ -4,17 +4,20 @@ defmodule OuterBrain.Persistence.Application do
   use Application
 
   @impl true
-  def start(_type, _args) do
-    children =
-      if Application.get_env(:outer_brain_persistence, :enabled, false) do
-        [OuterBrain.Persistence.Repo]
-      else
-        []
-      end
-
-    Supervisor.start_link(children,
+  def start(_type, args) do
+    Supervisor.start_link(children(args),
       strategy: :one_for_one,
       name: OuterBrain.Persistence.Supervisor
     )
   end
+
+  @doc false
+  @spec children(keyword()) :: [Supervisor.child_spec() | module() | {module(), term()}]
+  def children(args) when is_list(args) do
+    if Keyword.get(args, :enabled, false) do
+      [Keyword.get(args, :repo_child, OuterBrain.Persistence.Repo)]
+    else
+      []
+    end
+  end
 end

core/outer_brain_persistence/lib/outer_brain/persistence/application.ex

@@ -0,0 +1,20 @@
+defmodule OuterBrain.Persistence.JournalMapper do
+  @moduledoc false
+
+  alias OuterBrain.Journal.Tables.SemanticJournalEntryRecord
+
+  @spec from_schema(struct()) :: SemanticJournalEntryRecord.t()
+  def from_schema(schema) do
+    {:ok, entry} =
+      SemanticJournalEntryRecord.new(%{
+        entry_id: schema.entry_id,
+        session_id: schema.session_id,
+        causal_unit_id: schema.causal_unit_id,
+        entry_type: schema.entry_type,
+        recorded_at: schema.recorded_at,
+        payload: schema.payload
+      })
+
+    entry
+  end
+end

core/outer_brain_persistence/lib/outer_brain/persistence/mappers/journal_mapper.ex

@@ -0,0 +1,16 @@
+defmodule OuterBrain.Persistence.LeaseMapper do
+  @moduledoc false
+
+  alias OuterBrain.Contracts.Lease
+
+  @spec from_schema(struct()) :: Lease.t()
+  def from_schema(schema) do
+    %Lease{
+      session_id: schema.session_id,
+      holder: schema.holder,
+      lease_id: schema.lease_id,
+      epoch: schema.epoch,
+      expires_at: schema.expires_at
+    }
+  end
+end

core/outer_brain_persistence/lib/outer_brain/persistence/mappers/lease_mapper.ex

@@ -0,0 +1,34 @@
+defmodule OuterBrain.Persistence.RecoveryTaskMapper do
+  @moduledoc false
+
+  alias OuterBrain.Journal.Tables.RecoveryTaskRecord
+
+  @recovery_reasons [:ambiguous_submission]
+  @recovery_reasons_by_schema Map.new(@recovery_reasons, &{Atom.to_string(&1), &1})
+
+  @spec allowed_reason?(atom()) :: boolean()
+  def allowed_reason?(reason), do: reason in @recovery_reasons
+
+  @spec reason_to_schema(atom()) :: String.t()
+  def reason_to_schema(reason), do: Atom.to_string(reason)
+
+  @spec from_schema(struct()) :: RecoveryTaskRecord.t()
+  def from_schema(schema) do
+    %RecoveryTaskRecord{
+      task_id: schema.task_id,
+      session_id: schema.session_id,
+      reason: recovery_reason!(schema.reason),
+      status: schema.status
+    }
+  end
+
+  defp recovery_reason!(reason) when is_binary(reason) do
+    case Map.fetch(@recovery_reasons_by_schema, reason) do
+      {:ok, reason_atom} ->
+        reason_atom
+
+      :error ->
+        raise ArgumentError, "unknown recovery task reason: #{inspect(reason)}"
+    end
+  end
+end

core/outer_brain_persistence/lib/outer_brain/persistence/mappers/recovery_task_mapper.ex

@@ -0,0 +1,35 @@
+defmodule OuterBrain.Persistence.ReplyPublicationMapper do
+  @moduledoc false
+
+  alias OuterBrain.Journal.Tables.ReplyPublicationRecord
+
+  @spec to_schema_attrs(String.t(), ReplyPublicationRecord.t()) :: map()
+  def to_schema_attrs(tenant_id, %ReplyPublicationRecord{} = publication) do
+    %{
+      publication_id: publication.publication_id,
+      tenant_id: tenant_id,
+      causal_unit_id: publication.causal_unit_id,
+      phase: publication.phase,
+      state: publication.state,
+      dedupe_key: publication.dedupe_key,
+      body: publication.body,
+      body_ref: publication.body_ref
+    }
+  end
+
+  @spec from_schema(struct()) :: ReplyPublicationRecord.t()
+  def from_schema(schema) do
+    {:ok, publication} =
+      ReplyPublicationRecord.new(%{
+        publication_id: schema.publication_id,
+        causal_unit_id: schema.causal_unit_id,
+        phase: schema.phase,
+        state: schema.state,
+        dedupe_key: schema.dedupe_key,
+        body: schema.body,
+        body_ref: schema.body_ref
+      })
+
+    publication
+  end
+end

core/outer_brain_persistence/lib/outer_brain/persistence/mappers/reply_publication_mapper.ex

@@ -0,0 +1,16 @@
+defmodule OuterBrain.Persistence.SemanticFailureMapper do
+  @moduledoc false
+
+  alias OuterBrain.Contracts.SemanticFailure
+
+  @spec from_schema!(struct()) :: SemanticFailure.t()
+  def from_schema!(schema) do
+    case SemanticFailure.from_payload(schema.payload) do
+      {:ok, failure} ->
+        failure
+
+      {:error, reason} ->
+        raise ArgumentError, "invalid semantic failure payload: #{inspect(reason)}"
+    end
+  end
+end

core/outer_brain_persistence/lib/outer_brain/persistence/mappers/semantic_failure_mapper.ex

@@ -0,0 +1,23 @@
+defmodule OuterBrain.Persistence.OptionAccess do
+  @moduledoc false
+
+  @missing :__outer_brain_persistence_option_missing__
+
+  @spec to_map(keyword() | map()) :: map()
+  def to_map(opts) when is_list(opts), do: Map.new(opts)
+  def to_map(opts) when is_map(opts), do: opts
+
+  @spec value(map(), atom(), term()) :: term()
+  def value(attrs, field, default \\ nil) when is_map(attrs) and is_atom(field) do
+    string_field = Atom.to_string(field)
+
+    cond do
+      Map.has_key?(attrs, field) -> Map.fetch!(attrs, field)
+      Map.has_key?(attrs, string_field) -> Map.fetch!(attrs, string_field)
+      true -> default
+    end
+  end
+
+  @spec missing() :: atom()
+  def missing, do: @missing
+end