crucible_tensor_patch: initial repo and tensor patch migration

Author: nshkrdotcom

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: "28.3"
+          elixir-version: "1.18.4"
+      - uses: actions/cache@v4
+        with:
+          path: |
+            deps
+            _build
+          key: ${{ runner.os }}-mix-${{ hashFiles('mix.lock') }}
+          restore-keys: ${{ runner.os }}-mix-
+      - run: mix local.hex --force
+      - run: mix local.rebar --force
+      - run: mix ci

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 North Shore AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MIGRATION.md

@@ -0,0 +1,18 @@
+# Migration Notes
+
+This repo was scaffolded during TRINITY decomposition Phase 1 so
+`trinity_framework` could resolve local path dependencies before the public
+GitHub repos existed.
+
+Source material for the Phase 4 implementation:
+
+- `nshkrdotcom/trinity_coordinator` tag `v0.1.0-monolith`
+- source commit `64144a2983950e5fc9f2db2d26323a576c7379a1`
+- `lib/trinity_coordinator/runtime/backend_label.ex`
+- path traversal and param-tree patching portions of `lib/trinity_coordinator/sakana/artifact.ex`
+- patch/export flow from `lib/trinity_coordinator/sakana/exporter.ex`
+
+The implementation keeps the artifact runtime's product-specific loading and
+model-head wiring out of this package. This repo owns reusable tensor patch
+plans, path traversal, checksum/manifest output, resume behavior, and SVF-based
+patch application.

README.md

@@ -1,6 +1,11 @@
 # CrucibleTensorPatch
 
-**TODO: Add description**
+Deterministic tensor patch plans and patch application for model surgery.
+
+The package owns generic patch behavior: plan parsing, tensor path traversal,
+identity and SVF patch operations, manifest/checksum emission, resume/force
+rules, backend label round trips, and stage comparison. It intentionally avoids
+provider, tracing, and orchestration dependencies.
 
 ## Installation
 
@@ -19,3 +24,15 @@ Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_do
 and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
 be found at <https://hexdocs.pm/crucible_tensor_patch>.
 
+## CI
+
+```sh
+mix ci
+```
+
+Large local fixture checks are opt-in:
+
+```sh
+TRINITY_ARTIFACT_DIR=~/p/g/n/trinity_coordinator/priv/sakana_trinity/adapted_qwen3_0_6b_layer26 \
+  mix test --only large_tensor_patch
+```

build_support/dependency_sources.config.exs

@@ -0,0 +1,18 @@
+%{
+  deps: %{
+    crucible_safetensors: %{
+      path: "../crucible_safetensors",
+      github: %{repo: "North-Shore-AI/crucible_safetensors", branch: "main"},
+      hex: "~> 0.1.0",
+      default_order: [:path, :github, :hex],
+      publish_order: [:hex]
+    },
+    crucible_factorization: %{
+      path: "../crucible_factorization",
+      github: %{repo: "North-Shore-AI/crucible_factorization", branch: "main"},
+      hex: "~> 0.1.0",
+      default_order: [:path, :github, :hex],
+      publish_order: [:hex]
+    }
+  }
+}

build_support/dependency_sources.exs

@@ -0,0 +1,44 @@
+defmodule DependencySources do
+  @moduledoc false
+
+  def dep(app, repo_root, extra_opts \\ []) when is_atom(app) and is_binary(repo_root) do
+    repo_root = Path.expand(repo_root)
+    config = load_config!(repo_root)
+    dep_config = config |> Map.fetch!(:deps) |> Map.fetch!(app)
+    source = select_source!(dep_config, repo_root)
+    dep_tuple(app, dep_config, source, repo_root, extra_opts)
+  end
+
+  defp load_config!(repo_root) do
+    repo_root
+    |> Path.join("build_support/dependency_sources.config.exs")
+    |> Code.eval_file()
+    |> elem(0)
+  end
+
+  defp select_source!(config, repo_root) do
+    order = Map.get(config, :default_order, [:path, :github, :hex])
+
+    Enum.find(order, fn
+      :path -> config[:path] && File.exists?(Path.expand(config[:path], repo_root))
+      source -> Map.has_key?(config, source)
+    end) || raise ArgumentError, "no dependency source available"
+  end
+
+  defp dep_tuple(app, config, :path, repo_root, extra_opts) do
+    {app, Keyword.merge([path: Path.expand(config[:path], repo_root)], extra_opts)}
+  end
+
+  defp dep_tuple(app, config, :github, _repo_root, extra_opts) do
+    github = Map.fetch!(config, :github)
+    opts = github |> Map.delete(:repo) |> Map.to_list()
+    {app, Keyword.merge([github: github.repo], Keyword.merge(opts, extra_opts))}
+  end
+
+  defp dep_tuple(app, config, :hex, _repo_root, extra_opts) do
+    case extra_opts do
+      [] -> {app, Map.fetch!(config, :hex)}
+      opts -> {app, Map.fetch!(config, :hex), opts}
+    end
+  end
+end

lib/crucible/tensor_patch/backend_label.ex

@@ -0,0 +1,6 @@
+defmodule Crucible.TensorPatch.BackendLabel do
+  @moduledoc "Compatibility namespace for `CrucibleTensorPatch.BackendLabel`."
+
+  defdelegate from_label(label), to: CrucibleTensorPatch.BackendLabel
+  defdelegate from_label!(label), to: CrucibleTensorPatch.BackendLabel
+end

lib/crucible_tensor_patch/apply.ex

@@ -0,0 +1,190 @@
+defmodule CrucibleTensorPatch.Apply do
+  @moduledoc "Applies tensor patch plans to source tensors."
+
+  alias Crucible.Factorization.SVD
+  alias CrucibleSafetensors.{Checksum, Writer}
+  alias CrucibleTensorPatch.{Errors, Manifest, Operation, ParamTree, Plan, TensorPath}
+
+  @doc "Applies a plan to source tensors and writes output safetensors."
+  @spec apply(Plan.t(), map(), Path.t(), keyword()) :: {:ok, map()} | {:error, Exception.t()}
+  def apply(%Plan{} = plan, source_artifact, out_dir, opts \\ []) when is_map(source_artifact) do
+    {:ok, apply!(plan, source_artifact, out_dir, opts)}
+  rescue
+    exception -> {:error, exception}
+  end
+
+  @doc "Applies a plan, raising on invalid input."
+  @spec apply!(Plan.t(), map(), Path.t(), keyword()) :: map()
+  def apply!(%Plan{} = plan, source_artifact, out_dir, opts \\ []) when is_map(source_artifact) do
+    opts = Keyword.validate!(opts, components: %{}, force: false, write_manifest?: true)
+    File.mkdir_p!(out_dir)
+
+    reports =
+      plan.operations
+      |> Enum.map(fn operation -> apply_operation!(operation, source_artifact, out_dir, opts) end)
+
+    manifest = Manifest.build(reports, source: plan.source)
+
+    if opts[:write_manifest?] do
+      Manifest.write!(out_dir, manifest)
+    end
+
+    manifest
+  end
+
+  @doc "Applies manifest-style adapted tensors into a params tree."
+  defdelegate patch_params!(params, manifest, tensors, opts \\ []), to: ParamTree, as: :patch!
+
+  defp apply_operation!(%Operation{} = operation, source_artifact, out_dir, opts) do
+    output_path = Path.join(out_dir, operation.output_path)
+    existing = existing_output_status(operation, output_path, opts)
+
+    case existing do
+      {:skip, report} ->
+        report
+
+      :write ->
+        tensor = build_tensor!(operation, source_artifact, opts[:components])
+        validate_tensor!(operation, tensor)
+        write_tensor!(operation, output_path, tensor)
+    end
+  end
+
+  defp existing_output_status(operation, output_path, opts) do
+    cond do
+      opts[:force] ->
+        :write
+
+      File.regular?(output_path) and is_binary(operation.expected_output_sha256) ->
+        actual = Checksum.file_sha256!(output_path)
+
+        if actual == operation.expected_output_sha256 do
+          {:skip, report(operation, output_path, actual, "complete", true)}
+        else
+          raise Errors,
+                "resume checksum mismatch for #{operation.id}: expected #{operation.expected_output_sha256}, got #{actual}"
+        end
+
+      true ->
+        :write
+    end
+  end
+
+  defp build_tensor!(%Operation{operation: :identity} = operation, source_artifact, _components) do
+    fetch_source_tensor!(source_artifact, operation)
+  end
+
+  defp build_tensor!(%Operation{operation: :svf_apply} = operation, source_artifact, components) do
+    source = fetch_source_tensor!(source_artifact, operation)
+    inputs = operation.inputs || %{}
+
+    decomposition = %{
+      u: fetch_input!(inputs, components, "u"),
+      s: fetch_input!(inputs, components, "s"),
+      v: fetch_input!(inputs, components, "v")
+    }
+
+    offsets = fetch_input!(inputs, components, "scale_offsets")
+
+    decomposition
+    |> SVD.reconstruct(Nx.as_type(offsets, Nx.type(decomposition.s)))
+    |> Nx.as_type(Nx.type(source))
+  end
+
+  defp fetch_source_tensor!(source_artifact, operation) do
+    cond do
+      operation.source_path && Map.has_key?(source_artifact, operation.source_path) ->
+        Map.fetch!(source_artifact, operation.source_path)
+
+      operation.segments ->
+        source_artifact
+        |> TensorPath.fetch!(
+          TensorPath.normalize(operation.segments, operation.source_path),
+          operation.source_path
+        )
+
+      operation.source_path ->
+        source_artifact
+        |> TensorPath.fetch!(
+          TensorPath.normalize(nil, operation.source_path),
+          operation.source_path
+        )
+
+      true ->
+        raise Errors, "operation #{operation.id} has no source_path"
+    end
+  end
+
+  defp fetch_input!(inputs, components, name) do
+    value = Map.get(inputs, name) || Map.get(inputs, String.to_atom(name))
+
+    cond do
+      match?(%Nx.Tensor{}, value) -> value
+      is_binary(value) -> Map.fetch!(components, value)
+      true -> raise Errors, "missing input #{inspect(name)}"
+    end
+  end
+
+  defp validate_tensor!(operation, %Nx.Tensor{} = tensor) do
+    expected_shape = normalize_shape(operation.expected_shape)
+
+    if expected_shape && Nx.shape(tensor) != expected_shape do
+      raise Errors,
+            "operation #{operation.id} shape mismatch: expected #{inspect(expected_shape)}, got #{inspect(Nx.shape(tensor))}"
+    end
+
+    if operation.expected_dtype &&
+         normalize_dtype(Nx.type(tensor)) != normalize_dtype(operation.expected_dtype) do
+      raise Errors,
+            "operation #{operation.id} dtype mismatch: expected #{inspect(operation.expected_dtype)}, got #{inspect(Nx.type(tensor))}"
+    end
+
+    :ok
+  end
+
+  defp write_tensor!(operation, output_path, tensor) do
+    Writer.write!(%{operation.id => tensor_payload(tensor)}, output_path)
+    checksum = Checksum.file_sha256!(output_path)
+    report(operation, output_path, checksum, "complete", false)
+  end
+
+  defp tensor_payload(%Nx.Tensor{} = tensor) do
+    host = Nx.backend_transfer(tensor, Nx.BinaryBackend)
+
+    %{
+      dtype: writer_dtype!(Nx.type(host)),
+      shape: host |> Nx.shape() |> Tuple.to_list(),
+      data: Nx.to_binary(host)
+    }
+  end
+
+  defp report(operation, output_path, checksum, status, skipped?) do
+    %{
+      "id" => operation.id,
+      "operation" => Atom.to_string(operation.operation),
+      "source_path" => operation.source_path,
+      "output_path" => output_path,
+      "status" => status,
+      "skipped" => skipped?,
+      "sha256" => checksum
+    }
+  end
+
+  defp writer_dtype!({:f, 16}), do: :f16
+  defp writer_dtype!({:bf, 16}), do: :bf16
+  defp writer_dtype!({:f, 32}), do: :f32
+  defp writer_dtype!({:s, 32}), do: :i32
+  defp writer_dtype!({:s, 64}), do: :i64
+  defp writer_dtype!(type), do: raise(Errors, "unsupported output dtype #{inspect(type)}")
+
+  defp normalize_shape(nil), do: nil
+  defp normalize_shape(shape) when is_tuple(shape), do: shape
+  defp normalize_shape(shape) when is_list(shape), do: List.to_tuple(shape)
+  defp normalize_dtype({:f, 16}), do: "f16"
+  defp normalize_dtype({:bf, 16}), do: "bf16"
+  defp normalize_dtype({:f, 32}), do: "f32"
+  defp normalize_dtype({:s, 32}), do: "i32"
+  defp normalize_dtype({:s, 64}), do: "i64"
+  defp normalize_dtype(dtype) when is_atom(dtype), do: Atom.to_string(dtype)
+  defp normalize_dtype(dtype), do: inspect(dtype)
+end

lib/crucible_tensor_patch/backend_label.ex

@@ -0,0 +1,32 @@
+defmodule CrucibleTensorPatch.BackendLabel do
+  @moduledoc "Recovers an Nx backend specifier from a stored backend label."
+
+  require Logger
+
+  @type backend_spec :: module() | {module(), keyword()}
+
+  @doc "Returns `{:ok, backend_spec}` for known labels."
+  @spec from_label(String.t()) ::
+          {:ok, backend_spec()} | {:error, {:unknown_backend_label, String.t()}}
+  def from_label("EXLA.Backend<cuda" <> _), do: {:ok, {EXLA.Backend, client: :cuda}}
+  def from_label("EXLA.Backend<host" <> _), do: {:ok, {EXLA.Backend, client: :host}}
+  def from_label("Nx.BinaryBackend"), do: {:ok, Nx.BinaryBackend}
+  def from_label("EMLX.Backend" <> _), do: {:ok, {EMLX.Backend, device: :gpu}}
+  def from_label(other) when is_binary(other), do: {:error, {:unknown_backend_label, other}}
+
+  @doc "Returns a backend spec, falling back audibly to `Nx.BinaryBackend` for unknown labels."
+  @spec from_label!(String.t()) :: backend_spec()
+  def from_label!(label) when is_binary(label) do
+    case from_label(label) do
+      {:ok, backend_spec} ->
+        backend_spec
+
+      {:error, {:unknown_backend_label, ^label}} ->
+        Logger.warning(
+          "unknown backend label #{inspect(label)}, falling back to Nx.BinaryBackend"
+        )
+
+        Nx.BinaryBackend
+    end
+  end
+end

lib/crucible_tensor_patch/errors.ex

@@ -0,0 +1,5 @@
+defmodule CrucibleTensorPatch.Errors do
+  @moduledoc "Raised for invalid tensor patch plans or patch inputs."
+
+  defexception [:message]
+end