feat: add context abi contracts

Author: nshkrdotcom

.blitz/test_state_v1/indexes/task_states.ndjson

@@ -78,8 +78,8 @@ The workspace currently contains these active families:
   `outer_brain_persistence`, `outer_brain_runtime`,
   `outer_brain_restart_authority`, and `outer_brain_quality` for the core
   semantic runtime.
-- `outer_brain_prompting`, `prompt_fabric`, `context_budget`,
-  `memory_contracts`, `memory_engine`, `guardrail_contracts`,
+- `outer_brain_context_abi`, `outer_brain_prompting`, `prompt_fabric`,
+  `context_budget`, `memory_contracts`, `memory_engine`, `guardrail_contracts`,
   `guardrail_engine`, `eval_runner`, and `token_meter` for prompt/context,
   memory, guardrail, eval, and cost-sensitive semantic support.
 - `outer_brain_authority_evidence`, `ai_artifact_contracts`, and
@@ -181,6 +181,8 @@ Adaptive layer additions:
 - `core/ai_artifact_contracts`: ref-only artifact identity for prompt, role,
   skill, GEPA, eval, replay, router, provider, endpoint, promotion, and
   rollback refs.
+- `core/context_abi`: ref-only Context ABI packet/unit/receipt/failure
+  contracts and deterministic packet hashes for governed model execution.
 - `core/optimization_artifact_store`: ref-only artifact graph history for
   candidate lineage, eval evidence, promotion, and rollback decisions.
 

README.md

@@ -3,6 +3,28 @@ siblings_root = Path.expand("..", repo_root)
 
 %{
   deps: %{
+    ground_plane_contracts: %{
+      path: Path.join(siblings_root, "ground_plane/core/ground_plane_contracts"),
+      github: %{
+        repo: "nshkrdotcom/ground_plane",
+        branch: "main",
+        subdir: "core/ground_plane_contracts"
+      },
+      hex: "~> 0.1.0",
+      default_order: [:path, :github, :hex],
+      publish_order: [:hex]
+    },
+    jido_integration_provider_classification: %{
+      path: Path.join(siblings_root, "jido_integration/core/provider_classification"),
+      github: %{
+        repo: "agentjido/jido_integration",
+        branch: "main",
+        subdir: "core/provider_classification"
+      },
+      hex: "~> 0.1.0",
+      default_order: [:path, :github, :hex],
+      publish_order: [:hex]
+    },
     citadel_domain_surface: %{
       path: Path.join(siblings_root, "citadel/surfaces/citadel_domain_surface"),
       github: %{

build_support/dependency_sources.config.exs

@@ -11,6 +11,12 @@ defmodule OuterBrain.Build.WeldContract do
 
   @repo_root Path.expand("..", __DIR__)
 
+  @manifest_dependencies [
+    :ground_plane_contracts,
+    :jido_integration_provider_classification,
+    :mezzanine_eval_engine
+  ]
+
   @artifact_docs [
     "README.md",
     "docs/overview.md",
@@ -33,6 +39,7 @@ defmodule OuterBrain.Build.WeldContract do
       publication: [
         internal_only: [
           ".",
+          "core/context_abi",
           "core/memory_contracts",
           "core/memory_engine",
           "core/context_budget",
@@ -77,22 +84,37 @@ defmodule OuterBrain.Build.WeldContract do
   end
 
   defp dependencies do
-    [
-      mezzanine_eval_engine: manifest_dependency(:mezzanine_eval_engine)
-    ]
+    Enum.map(@manifest_dependencies, fn app ->
+      {app, manifest_dependency(app)}
+    end)
   end
 
   defp manifest_dependency(app) do
-    case DependencySources.deps(@repo_root, publish?: true) |> List.keyfind(app, 0) do
-      {^app, requirement} when is_binary(requirement) ->
-        [requirement: requirement]
+    config = Map.fetch!(dependency_configs(), app)
+    github = Map.fetch!(config, :github)
+
+    [opts: github_opts(github)]
+  end
+
+  defp dependency_configs do
+    {config, _binding} =
+      @repo_root
+      |> Path.join("build_support/dependency_sources.config.exs")
+      |> Code.eval_file()
+
+    Map.new(config[:deps], fn {app, dep_config} -> {app, Map.new(dep_config)} end)
+  end
+
+  defp github_opts(github) do
+    github = Map.new(github)
+    repo = Map.fetch!(github, :repo)
 
-      {^app, requirement, opts} when is_binary(requirement) ->
-        [requirement: requirement, opts: opts]
+    opts =
+      github
+      |> Map.take([:branch, :ref, :tag, :subdir])
+      |> Enum.sort_by(fn {key, _value} -> key end)
 
-      {^app, opts} when is_list(opts) ->
-        [opts: opts]
-    end
+    Keyword.merge([github: repo], opts)
   end
 end
 

build_support/weld.exs

@@ -6,6 +6,7 @@ defmodule OuterBrain.Build.WorkspaceContract do
     "core/outer_brain_journal",
     "core/outer_brain_persistence",
     "core/outer_brain_core",
+    "core/context_abi",
     "core/outer_brain_prompting",
     "core/outer_brain_quality",
     "core/outer_brain_runtime",

build_support/workspace_contract.exs

@@ -0,0 +1,3 @@
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

core/context_abi/.formatter.exs

@@ -0,0 +1,11 @@
+# OuterBrain Context ABI
+
+Ref-only Context ABI contracts for governed model execution.
+
+This package owns the MVP context packet surface, deterministic packet hashes,
+context unit validation, context packet receipts, and owner-local failure
+reason-code shape. It does not render provider-native payloads, authorize
+restricted context, execute models, or persist workflow truth.
+
+The package uses `GroundPlane.Boundary.Codec` through GroundPlane contracts for
+canonical boundary encoding and `sha256:` digest generation.

core/context_abi/README.md

@@ -0,0 +1,14 @@
+defmodule OuterBrain.ContextABI do
+  @moduledoc """
+  Public facade for the OuterBrain Context ABI MVP.
+  """
+
+  alias OuterBrain.ContextABI.{Compiler, ContextPacket, ContextPacketReceipt, Failure}
+
+  @spec compile(Compiler.compile_request(), keyword()) ::
+          {:ok, ContextPacket.t(), ContextPacketReceipt.t()} | {:error, Failure.t()}
+  def compile(request, opts \\ []) do
+    compiler = Keyword.get(opts, :compiler, Compiler)
+    compiler.compile(request, Keyword.delete(opts, :compiler))
+  end
+end

core/context_abi/lib/outer_brain/context_abi.ex

@@ -0,0 +1,34 @@
+defmodule OuterBrain.ContextABI.Canonical do
+  @moduledoc """
+  Canonical encoding and digest helpers for Context ABI facts.
+  """
+
+  alias GroundPlane.Boundary.Codec
+  alias OuterBrain.ContextABI.ContextPacket
+
+  @spec digest(term()) :: String.t()
+  def digest(term), do: term |> normalize_for_boundary() |> Codec.digest()
+
+  @spec packet_hash(ContextPacket.t()) :: String.t()
+  def packet_hash(%ContextPacket{} = packet) do
+    packet
+    |> ContextPacket.hash_input()
+    |> digest()
+  end
+
+  @spec normalize_for_boundary(term()) :: term()
+  def normalize_for_boundary(%{__struct__: _} = value),
+    do: value |> Map.from_struct() |> normalize_for_boundary()
+
+  def normalize_for_boundary(%{} = map) do
+    map
+    |> Enum.map(fn {key, value} -> {to_string(key), normalize_for_boundary(value)} end)
+    |> Map.new()
+  end
+
+  def normalize_for_boundary(values) when is_list(values),
+    do: Enum.map(values, &normalize_for_boundary/1)
+
+  def normalize_for_boundary(value) when is_atom(value), do: Atom.to_string(value)
+  def normalize_for_boundary(value), do: value
+end

core/context_abi/lib/outer_brain/context_abi/canonical.ex

@@ -0,0 +1,45 @@
+defmodule OuterBrain.ContextABI.Compiler do
+  @moduledoc """
+  Behaviour and deterministic MVP compiler for Context ABI packets.
+  """
+
+  alias OuterBrain.ContextABI.{ContextPacket, ContextPacketReceipt, Failure}
+
+  @type compile_request :: %{
+          required(:tenant_ref) => String.t(),
+          required(:user_request_ref) => String.t(),
+          required(:system_instruction_ref) => String.t(),
+          optional(:memory_refs) => [String.t()],
+          required(:budget_ref) => String.t(),
+          required(:model_class_allowlist) => [String.t()],
+          required(:route_policy_ref) => String.t(),
+          required(:trace_ref) => String.t()
+        }
+
+  @callback compile(compile_request(), keyword()) ::
+              {:ok, ContextPacket.t(), ContextPacketReceipt.t()} | {:error, Failure.t()}
+
+  @spec compile(compile_request(), keyword()) ::
+          {:ok, ContextPacket.t(), ContextPacketReceipt.t()} | {:error, Failure.t()}
+  def compile(request, opts \\ [])
+
+  def compile(request, opts) when is_map(request) and is_list(opts) do
+    request
+    |> ContextPacket.new()
+    |> case do
+      {:ok, packet} -> {:ok, packet, ContextPacketReceipt.compiled(packet)}
+      {:error, %Failure{} = failure} -> {:error, failure}
+    end
+  end
+
+  def compile(_request, _opts) do
+    {:ok, failure} =
+      Failure.new(%{
+        owner: :outer_brain,
+        reason_code: "outer_brain.context.invalid_compile_request.v1",
+        safe_message: "context compile request is invalid"
+      })
+
+    {:error, failure}
+  end
+end