feat: persist governed semantic turn artifacts

Author: nshkrdotcom

core/outer_brain_journal/lib/outer_brain/journal/tables.ex

@@ -246,6 +246,11 @@ defmodule OuterBrain.Journal.Tables do
       :dedupe_key,
       :body,
       :body_ref,
+      :run_ref,
+      :turn_ref,
+      :attempt_ref,
+      :reply_artifact_ref,
+      :next_semantic_ref,
       persistence_posture: PersistencePosture.memory(:publication_state)
     ]
 
@@ -257,6 +262,11 @@ defmodule OuterBrain.Journal.Tables do
             dedupe_key: String.t(),
             body: String.t(),
             body_ref: ReplyBodyBoundary.body_ref(),
+            run_ref: String.t() | nil,
+            turn_ref: String.t() | nil,
+            attempt_ref: String.t() | nil,
+            reply_artifact_ref: String.t() | nil,
+            next_semantic_ref: String.t() | nil,
             persistence_posture: PersistencePosture.t()
           }
 
@@ -286,6 +296,11 @@ defmodule OuterBrain.Journal.Tables do
            dedupe_key: dedupe_key,
            body: body,
            body_ref: body_ref,
+           run_ref: Map.get(attrs, :run_ref),
+           turn_ref: Map.get(attrs, :turn_ref),
+           attempt_ref: Map.get(attrs, :attempt_ref),
+           reply_artifact_ref: Map.get(attrs, :reply_artifact_ref),
+           next_semantic_ref: Map.get(attrs, :next_semantic_ref),
            persistence_posture: PersistencePosture.resolve(:publication_state, attrs)
          }}
       else

core/outer_brain_persistence/README.md

@@ -9,22 +9,24 @@ Canonical durable tables include:
 - `recovery_tasks`
 - `reply_publications`
 - `outer_brain_artifact_descriptors`
+- `outer_brain_artifact_payloads`
 - `outer_brain_semantic_contexts`
 
 This package owns the canonical write path for those rows. In-memory runtime
 state may mirror hot rows, but it does not own truth.
 
 Semantic failure carriers are recorded as idempotent
 `semantic_journal_entries` with `entry_type = "semantic_failure"` and payloads
-encoded through `OuterBrain.Contracts.SemanticFailure`. Reply publication
-writes are idempotent by `dedupe_key`, so restart replay can update the durable
-publication row without creating a second user-visible publication.
-
-Semantic-context writes atomically persist a secret-free
-`GroundPlane.Contracts.ArtifactDescriptor` and immutable
-`OuterBrain.Contracts.SemanticContextProvenance`. The PostgreSQL full-text
-index covers opaque semantic, provider, model, artifact, and provenance refs;
-it never indexes raw prompt or provider bodies.
+encoded through `OuterBrain.Contracts.SemanticFailure`. Final reply publication
+writes are immutable and idempotent by exact `dedupe_key`/lineage agreement, so
+restart replay cannot create or mutate a second user-visible publication.
+
+Prompt-context and reply-continuation writes atomically persist immutable
+content-addressed payloads, secret-free
+`GroundPlane.Contracts.ArtifactDescriptor` rows, semantic provenance, and exact
+run/turn/attempt lineage. Payload reads require tenant, reader, operation, and
+authority-packet agreement. The PostgreSQL full-text index covers only opaque
+refs; it never indexes prompt or provider bodies.
 
 Production hosts supervise
 `{OuterBrain.Persistence.DurableSupervisor, profile: :durable_redacted,

core/outer_brain_persistence/docs/persistence.md

@@ -3,8 +3,8 @@
 ## Production contract
 
 `core/outer_brain_persistence` owns PostgreSQL truth for semantic-session
-leases, journal entries, recovery tasks, reply publications, artifact
-descriptors, and semantic-context provenance. The sole production profile is
+leases, journal entries, recovery tasks, reply publications, immutable artifact
+descriptors/payloads, and semantic-context provenance. The sole production profile is
 `:durable_redacted`; missing, disabled, memory, and unknown profiles fail before
 a repository child is selected.
 
@@ -44,16 +44,22 @@ OuterBrain.Persistence.Store.preflight(
 
 ## Semantic context and artifact boundaries
 
-`Store.record_semantic_context/3` atomically records an immutable,
-secret-free `GroundPlane.Contracts.ArtifactDescriptor` and the matching
-`OuterBrain.Contracts.SemanticContextProvenance`. Exact replays are idempotent;
-reuse of an artifact, semantic, or idempotency reference with different facts
-fails closed. Tenant scope is required on every write and read.
+`Store.record_prompt_context/2` atomically records the content-addressed context
+and prompt-manifest payloads, their secret-free descriptors, and matching
+semantic provenance/lineage. `Store.publish_reply_continuation/2` atomically
+records the normalized final reply, next context revision, publication, and a
+safe journal fact. Exact replays are idempotent; reuse of an artifact, semantic,
+publication, or idempotency reference with different facts fails closed. Tenant
+scope is required on every write and read.
+
+`Store.resolve_artifact_payload/3` requires exact tenant, reader, operation,
+and authority-packet agreement. Artifact references are not bearer authority.
 
 The semantic index contains only opaque semantic, provider, model, artifact,
-and provenance refs. Raw prompts, provider bodies, signed object-store URLs,
-credentials, and credential-shaped metadata are forbidden. Object locations
-remain opaque owner-authorized refs.
+run, turn, and provenance refs. Provider-native bodies, private reasoning,
+credentials, signed object-store URLs, and credential-shaped metadata are
+forbidden. Payloads are immutable and accessible only through the owner API;
+locations remain opaque owner-authorized refs.
 
 ## Test boundary
 

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

@@ -0,0 +1,57 @@
+defmodule OuterBrain.Persistence.ArtifactAccess do
+  @moduledoc """
+  Safe, exact authorization evidence required to resolve an OuterBrain artifact.
+
+  An artifact ref is never bearer authority. The tenant, reader, operation, and
+  authority packet must all agree with the immutable payload row.
+  """
+
+  @enforce_keys [:tenant_ref, :reader_ref, :operation_ref, :authority_packet_ref]
+  defstruct @enforce_keys
+
+  @type t :: %__MODULE__{
+          tenant_ref: String.t(),
+          reader_ref: String.t(),
+          operation_ref: String.t(),
+          authority_packet_ref: String.t()
+        }
+
+  @spec new(map() | keyword() | t()) :: {:ok, t()} | {:error, :invalid_artifact_access}
+  def new(%__MODULE__{} = access), do: access |> Map.from_struct() |> new()
+
+  def new(attrs) when is_map(attrs) or is_list(attrs) do
+    attrs = Map.new(attrs)
+
+    with {:ok, tenant_ref} <- required(attrs, :tenant_ref),
+         {:ok, reader_ref} <- required(attrs, :reader_ref),
+         {:ok, operation_ref} <- required(attrs, :operation_ref),
+         {:ok, authority_packet_ref} <- required(attrs, :authority_packet_ref) do
+      {:ok,
+       %__MODULE__{
+         tenant_ref: tenant_ref,
+         reader_ref: reader_ref,
+         operation_ref: operation_ref,
+         authority_packet_ref: authority_packet_ref
+       }}
+    else
+      _other -> {:error, :invalid_artifact_access}
+    end
+  end
+
+  def new(_attrs), do: {:error, :invalid_artifact_access}
+
+  @spec new!(map() | keyword() | t()) :: t()
+  def new!(attrs) do
+    case new(attrs) do
+      {:ok, access} -> access
+      {:error, reason} -> raise ArgumentError, "invalid artifact access: #{inspect(reason)}"
+    end
+  end
+
+  defp required(attrs, key) do
+    case Map.get(attrs, key, Map.get(attrs, Atom.to_string(key))) do
+      value when is_binary(value) and value != "" -> {:ok, value}
+      _other -> :error
+    end
+  end
+end

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

@@ -3,8 +3,8 @@ defmodule OuterBrain.Persistence.ReplyPublicationMapper do
 
   alias OuterBrain.Journal.Tables.ReplyPublicationRecord
 
-  @spec to_schema_attrs(String.t(), ReplyPublicationRecord.t()) :: map()
-  def to_schema_attrs(tenant_id, %ReplyPublicationRecord{} = publication) do
+  @spec to_schema_attrs(String.t(), ReplyPublicationRecord.t(), map()) :: map()
+  def to_schema_attrs(tenant_id, %ReplyPublicationRecord{} = publication, lineage) do
     %{
       publication_id: publication.publication_id,
       tenant_id: tenant_id,
@@ -13,7 +13,12 @@ defmodule OuterBrain.Persistence.ReplyPublicationMapper do
       state: publication.state,
       dedupe_key: publication.dedupe_key,
       body: publication.body,
-      body_ref: publication.body_ref
+      body_ref: publication.body_ref,
+      run_ref: lineage.run_ref,
+      turn_ref: lineage.turn_ref,
+      attempt_ref: lineage.attempt_ref,
+      reply_artifact_ref: lineage.reply_artifact_ref,
+      next_semantic_ref: lineage.next_semantic_ref
     }
   end
 
@@ -27,7 +32,12 @@ defmodule OuterBrain.Persistence.ReplyPublicationMapper do
         state: schema.state,
         dedupe_key: schema.dedupe_key,
         body: schema.body,
-        body_ref: schema.body_ref
+        body_ref: schema.body_ref,
+        run_ref: schema.run_ref,
+        turn_ref: schema.turn_ref,
+        attempt_ref: schema.attempt_ref,
+        reply_artifact_ref: schema.reply_artifact_ref,
+        next_semantic_ref: schema.next_semantic_ref
       })
 
     publication

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

@@ -4,14 +4,17 @@ defmodule OuterBrain.Persistence.SemanticContextMapper do
   alias GroundPlane.Boundary.Codec
   alias OuterBrain.Contracts.SemanticContextProvenance
 
-  @spec to_schema_attrs(SemanticContextProvenance.t(), String.t()) :: map()
-  def to_schema_attrs(%SemanticContextProvenance{} = provenance, artifact_ref) do
-    attrs = SemanticContextProvenance.to_map(provenance)
+  @spec to_schema_attrs(SemanticContextProvenance.t(), map()) :: map()
+  def to_schema_attrs(%SemanticContextProvenance{} = provenance, lineage) do
+    provenance_attrs = SemanticContextProvenance.to_map(provenance)
+    attrs = Map.merge(provenance_attrs, lineage)
 
     attrs
-    |> Map.put(:artifact_ref, artifact_ref)
-    |> Map.put(:provenance_digest, Codec.digest(attrs))
-    |> Map.put(:search_document, search_document(provenance, artifact_ref))
+    |> Map.put(
+      :provenance_digest,
+      Codec.digest(%{provenance: provenance_attrs, lineage: lineage})
+    )
+    |> Map.put(:search_document, search_document(provenance, lineage))
   end
 
   @spec from_schema(struct()) :: SemanticContextProvenance.t()
@@ -47,12 +50,28 @@ defmodule OuterBrain.Persistence.SemanticContextMapper do
     provenance
   end
 
-  defp search_document(provenance, artifact_ref) do
+  @spec lineage_from_schema(struct()) :: map()
+  def lineage_from_schema(schema) do
+    %{
+      run_ref: schema.run_ref,
+      turn_ref: schema.turn_ref,
+      context_artifact_ref: schema.context_artifact_ref,
+      prompt_artifact_ref: schema.prompt_artifact_ref,
+      model_profile_ref: schema.model_profile_ref,
+      memory_snapshot_refs: schema.memory_snapshot_refs,
+      previous_semantic_ref: schema.previous_semantic_ref
+    }
+  end
+
+  defp search_document(provenance, lineage) do
     [
       provenance.semantic_ref,
       provenance.provider_ref,
       provenance.model_ref,
-      artifact_ref
+      lineage.context_artifact_ref,
+      lineage.prompt_artifact_ref,
+      lineage.run_ref,
+      lineage.turn_ref
       | provenance.provenance_refs
     ]
     |> Enum.join(" ")